Skip to main content
Connic
Platform

Deployment

Deploy your agents to Connic cloud using Git-based automatic deployments or CLI deployments.

Last updated
On this page

Overview

Connic supports two deployment methods depending on your workflow:

Git Integration

Connect a Git repository to your project. Pushing to configured branches triggers deployments.

  • • Automatic on push
  • • Branch-to-environment mapping
  • • Supports GitHub, GitLab, and Bitbucket
CLI Deployments

Deploy locally or from a CI/CD pipeline when the Connic project has no connected Git repository.

  • • Source can live with any Git provider
  • • Use in CI/CD pipelines
  • • Target the default or a specific environment

Git Integration

Connect your Git repository for automatic deployments on push. Connic supports GitHub, GitLab, and Bitbucket.

1

Connect Your Repository

  1. Go to Project Settings → Git & Environments
  2. Click Connect and select your provider (GitHub, GitLab, or Bitbucket)
  3. Authorize Connic to access your repositories. GitLab.com uses OAuth; for Self-Managed GitLab 15.5 or later, first add the instance under Account → Git Accounts with a personal access token that has the api scope. The GitLab user must be an administrator or have the Maintainer or Owner role on each repository.
  4. Select the repository containing your agents/ directory and any supporting project directories
  5. If your repo is a monorepo, set the Repository root directory to the path where your Connic SDK project lives (e.g. services/agents). Leave empty when the SDK files are at the repo root.
  6. Connic installs a webhook on the repository to detect pushes and pull or merge requests
2

Configure Environment Branches

  1. Open Project Settings → Git & Environments
  2. For each environment, set the Git Branch that triggers deployments
  3. Pushes to branches that are not mapped to any environment are ignored

For example:

  • • Production → main
  • • Staging → develop
  • • Development → feature/customer-import (optional)
3

Push to Deploy

Push to your configured branch. Connic detects the push via webhooks and creates a deployment.

terminal
# Push to trigger deployment
git add .
git commit -m "Update agents"
git push origin main

PR Testing

For GitHub and GitLab repositories, Connic can run the suite from a pull request or merge request whose source branch is in the connected repository. It reports connic/pr-tests as a commit status. The target branch selects the mapped environment, and a configured test-environment override keeps the run away from production state.

See PR Testing for setup, provider-specific merge checks, rerun behavior, and shared-environment guidance.

CLI Deployments

Use the CLI to deploy from your local machine or CI/CD pipeline when:

  • The project has no Git repository connected in Connic
  • You deploy from a local checkout or CI/CD pipeline
  • Your source repository uses any Git provider or no provider
1

Install the SDK

terminal
pip install connic-composer-sdk
2

Authenticate

Run the login command. It opens the dashboard to create an API key, then prompts for the resulting login token:

terminal
connic login

This creates a .connic file:

.connic
{
  "api_key": "cnc_xxxxxxxxxxxx",
  "project_id": "your-project-uuid"
}

For CI/CD, use environment variables instead: CONNIC_API_KEY and CONNIC_PROJECT_ID

3

Get Your Environment ID

Go to Project Settings → Git & Environments and copy the environment ID you want to deploy to.

4

Deploy

terminal
# Deploy to default environment
connic deploy

# Deploy to a specific environment
connic deploy --env <environment-id>

The CLI uploads supported files from agents/, tools/, middleware/, schemas/, guardrails/, hooks/, and tests/, plus requirements.txt. Nested files are included.

CI/CD Integration

Use the CLI in a CI/CD pipeline when the Connic project has no connected Git repository. The source repository can use any provider.

.github/workflows/deploy.yml
name: Deploy to Connic
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install connic-composer-sdk
      - run: connic deploy --env $CONNIC_ENV_ID
        env:
          CONNIC_API_KEY: ${{ secrets.CONNIC_API_KEY }}
          CONNIC_PROJECT_ID: ${{ secrets.CONNIC_PROJECT_ID }}
          CONNIC_ENV_ID: ${{ secrets.CONNIC_ENV_ID }}
.gitlab-ci.yml
deploy:
  stage: deploy
  script:
    - pip install connic-composer-sdk
    - connic deploy --env $CONNIC_ENV_ID
  variables:
    CONNIC_API_KEY: $CONNIC_API_KEY
    CONNIC_PROJECT_ID: $CONNIC_PROJECT_ID

Set CONNIC_API_KEY, CONNIC_PROJECT_ID, and CONNIC_ENV_ID as CI/CD secrets in your provider's settings.

What Happens During Deployment

Code is packaged and uploaded to Connic
Dependencies are installed and the deployment is built
The test suite runs when the project contains tests/
A successful deployment becomes available and receives traffic

Monitoring Deployments

View deployment status and logs in the Deployments tab:

  • See all deployments with status and duration
  • Click a deployment to view build logs
  • The currently serving deployment is marked "Active"
Deployments tab listing deployments with status, test result, and build duration. The currently serving deployment is marked Active.
The Deployments tab: each deployment with its status, deploy-gate test result, and build duration. The serving deployment is marked Active.
Open Projects

Test Phase (Deploy Gate)

When a project contains tests/, both Git and CLI deployments build the deployment, run the complete suite, and activate only after every case passes. The deployment detail page shows the live pipeline and per-case results.

See The Deploy Gate for test-environment overrides, result locations, and the CLI-only --skip-tests flag. Use the first-test guide to write the suite itself.

Rollback a Deployment

Activate another successful deployment from the Deployments tab:

  1. Open the Deployments tab and select a successful deployment
  2. Click the Activate button on that deployment
  3. Traffic is routed to the selected deployment without rebuilding it
Activation reuses the selected deployment and does not run another build.

When a Deployment Fails

When a build fails, the deployment is marked Failed and the active deployment continues serving traffic.

Investigating a failure:

  1. Open the Deployments tab and click the failed deployment
  2. Review the build logs to identify the error

Common failure reasons:

  • Missing dependencies in requirements.txt
  • Invalid agent YAML syntax (malformed config, missing required fields)
  • Python import errors in tools or middleware files

Explore the platform

Environments

Manage environments and branch mapping

Observability

Monitor runs, traces, and token usage

Testing

Declarative tests that gate every deploy

Variables

Configure secrets and settings per environment