Deployment

Agenten werden per Git-Push oder CLI in der connic cloud bereitgestellt. Deployment-Tests und Build Logs ermöglichen die Prüfung, bevor ein erfolgreiches Deployment aktiviert wird.

Überblick

connic unterstützt zwei Deployment-Methoden für unterschiedliche Workflows:

Git-Integration

Verbinde ein Git-Repository, um bei einem Push automatisch zu deployen. connic unterstützt GitHub, GitLab und Bitbucket.

1. 1

   Repository verbinden

   1. 1

      Öffne Projekt-Settings → Git & Environments

   2. 2

      Klicke auf Connect und wähle einen Provider aus (GitHub, GitLab oder Bitbucket)

   3. 3

      Erlaube connic den Zugriff auf die Repositories. GitLab.com verwendet OAuth. Für Self-Managed GitLab ab Version 15.5 wird die Instanz zuerst unter Account → Git Accounts mit einem Personal Access Token hinzugefügt, das den Scope api hat. Der GitLab-Benutzer muss Administrator sein oder in jedem Repository die Rolle Maintainer oder Owner haben.

   4. 4

      Wähle das Repository aus, das das Verzeichnis agents/ und alle unterstützenden Projekt-Verzeichnisse enthält

   5. 5

      Bei einem Monorepo wird Repository root directory auf den Pfad gesetzt, in dem das connic SDK Projekt liegt (z. B. services/agents). Lass das Feld leer, wenn die SDK-Dateien im Root-Verzeichnis des Repositories liegen.

   6. 6

      connic installiert einen Webhook im Repository, um Pushes sowie Pull oder Merge Requests zu erkennen

2. 2

   Environment-Branches konfigurieren

   1. 1

      Öffne Projekt-Settings → Git & Environments

   2. 2

      Lege für jedes Environment den Git Branch fest, der Deployments auslöst

   3. 3

      Pushes auf Branches, die keinem Environment zugeordnet sind, werden ignoriert

   Zum Beispiel:

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

   Per Push deployen

   Pushe auf den konfigurierten Branch. connic erkennt den Push über Webhooks und erstellt ein Deployment.

   terminal

   Copy

   # Per Push ein Deployment auslösen
   git add .
   git commit -m "Agenten aktualisieren"
   git push origin main

CLI Deployments

Die CLI eignet sich für Deployments von einem lokalen Rechner oder aus einer CI/CD-Pipeline, wenn:

• für das Projekt kein Git-Repository mit connic verbunden ist
• das Deployment aus einem lokalen Checkout oder einer CI/CD-Pipeline startet
• das Quell-Repository einen beliebigen Git-Provider oder keinen Provider nutzt

1. 1

   SDK installieren

   terminal

   Copy

   pip install connic-composer-sdk

2. 2

   Authentifizieren

   Führe den Login-Befehl aus. Er öffnet das Dashboard, um einen API Key zu erstellen, und fragt anschließend nach dem erzeugten Login-Token:

   terminal

   Copy

   connic login

   Dadurch wird eine Datei .connic erstellt:

   .connic

   Copy

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

   Für CI/CD werden stattdessen die Umgebungsvariablen CONNIC_API_KEY und CONNIC_PROJECT_ID verwendet.

3. 3

   Umgebung auswählen

   Zeige mit connic deploy --list die verfügbaren Ziele an. Umgebungen werden anhand ihres Namens ausgewählt; --env akzeptiert auch eine Environment-ID.

4. 4

   Deploy

   terminal

   Copy

   # Umgebung nach Namen auswählen und bestätigen
   connic deploy
   
   # Verfügbare Deployment-Ziele auflisten
   connic deploy --list
   
   # Ziel direkt auswählen, anschließend bestätigen
   connic deploy --env staging

   Ohne Flags listet die CLI die Umgebungen nach Namen auf. Wähle ein Ziel, prüfe die Deployment-Zusammenfassung und bestätige den Vorgang, bevor die CLI Dateien hochlädt.

   Die CLI lädt unterstützte Dateien aus agents/, tools/, middleware/, schemas/, guardrails/, hooks/, tests/ und connectors/ sowie requirements.txt hoch. Verschachtelte Dateien werden einbezogen.

CI/CD-Integration

Verwende die CLI in einer CI/CD-Pipeline, wenn das connic Projekt mit keinem Git-Repository verbunden ist. Das Quell-Repository kann jeden Provider nutzen. Für unbeaufsichtigte Deployments werden ein explizites --env und --yes übergeben.

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_NAME" --yes
        env:
          CONNIC_API_KEY: ${{ secrets.CONNIC_API_KEY }}
          CONNIC_PROJECT_ID: ${{ secrets.CONNIC_PROJECT_ID }}
          CONNIC_ENV_NAME: ${{ secrets.CONNIC_ENV_NAME }}

deploy:
  stage: deploy
  script:
    - pip install connic-composer-sdk
    - connic deploy --env "$CONNIC_ENV_NAME" --yes
  variables:
    CONNIC_API_KEY: $CONNIC_API_KEY
    CONNIC_PROJECT_ID: $CONNIC_PROJECT_ID

Hinterlege CONNIC_API_KEY, CONNIC_PROJECT_ID und CONNIC_ENV_NAME in den Einstellungen des Providers als CI/CD-Secrets.

Was während eines Deployments passiert

Ein Run nutzt das Deployment, das beim Start des Runs aktiv ist. Runs, die noch warten, wenn ein neues Deployment aktiv wird, starten auf dem neuen Deployment. Das gilt auch, wenn du ein früheres Deployment aktivierst.

Wird ein Deployment aktiv, wendet connic die darin im Code deklarierten Verbindungen an. Schlägt eine Änderung an einer Verbindung fehl, wird nichts aktiviert und das bisherige Deployment bedient weiterhin Anfragen. Siehe Verbindungen im Code.

Ein durch die Prüfung gestopptes Deployment erhält den Status Blocked. connic baut, testet und aktiviert es nicht. Öffne das Deployment, um die Hinweise zur Kontaktaufnahme mit dem Support zu sehen.

Deployments überwachen

Status und Logs der Deployments stehen im Tab Deployments:

• Sieh alle Deployments mit Status und Dauer
• Klicke auf ein Deployment, um die Build Logs anzuzeigen
• Das aktuell ausgelieferte Deployment ist mit „Active“ gekennzeichnet

Deployment zurücksetzen

Aktiviere im Tab Deployments ein anderes erfolgreiches Deployment:

1. 1

   Öffne den Tab Deployments und wähle ein erfolgreiches Deployment aus

2. 2

   Klicke für dieses Deployment auf den Button Activate

3. 3

   Der Traffic wird ohne erneuten Build an das ausgewählte Deployment geleitet

Das Aktivieren eines früheren Deployments stellt auch die darin im Code deklarierten Verbindungen wieder her, mit den Variablenwerten, die bei diesem Deployment galten. Der Aktivierungsdialog listet auf, welche Verbindungen angelegt, aktualisiert, zurückgeholt oder stillgelegt würden. Schlägt eine Änderung an einer Verbindung fehl, aktiviert Activate anyway das Deployment und überspringt die fehlerhaften Verbindungen.

Wenn ein Deployment fehlschlägt

Schlägt ein Build fehl, wird das Deployment als Failed markiert und das aktive Deployment bedient weiterhin Anfragen.

Schlägt bei der Aktivierung eine Änderung an einer Verbindung fehl, etwa wegen eines API-Fehlers beim Provider, bietet die Deployment-Seite Deploy anyway an. Damit wird der Commit erneut deployt, und die fehlerhaften Verbindungen werden übersprungen. Sie behalten ihren bisherigen Zustand bis zur nächsten Aktivierung.