Create changes from the build pipeline and report the result: GitLab CI and GitHub Actions

Jedes Deployment ist eine Änderung. Wer sie von Hand in knooing einträgt, vergisst es, oder trägt es zu spät ein. Mit der Pipeline-Anbindung legt Ihre Build-Pipeline den Change selbst an und meldet nach dem Rollout, ob er gelungen ist. So steht jedes Deployment im Change-Register, mit Zeitpunkt, Ergebnis und Verweis auf den Pipeline-Lauf. Das Ergebnis fließt in die Change-Kennzahlen ein, und ein Fehlschlag legt automatisch eine Nachbetrachtung an.

Dieser Artikel richtet sich an Entwicklerinnen und Entwickler. Die Anbindung nutzt zwei Aufrufe der Schnittstelle: POST /api/pipeline/changes legt den Change an, POST /api/pipeline/changes/<Change-ID>/status meldet das Ergebnis.

Beispiel im Artikel: Die Pipeline des Projekts „beispiel-portal“ der Beispiel GmbH legt bei jedem Deployment auf den Standard-Branch einen Change für den Service Auftragsportal an. Alle Schlüssel und IDs in den Beispielen sind Platzhalter.

Der Ablauf im Überblick

1. Vor dem Deployment legt der Job knooing-change-open den Change an und gibt die Change-ID an die späteren Jobs weiter.
2. Ihr Deployment läuft.
3. Danach meldet knooing-change-status das Ergebnis successful. Ist ein früherer Job fehlgeschlagen, meldet stattdessen knooing-change-status-failed das Ergebnis failed.

Warum so? Der Change entsteht, bevor etwas passiert, und das Ergebnis wird erst gemeldet, wenn es feststeht. Das entspricht dem Prozess von Hand: erst planen, dann umsetzen, dann das Ergebnis festhalten.

Schritt 1: Den Schlüssel anlegen und sicher hinterlegen

Legen Sie in knooing unter Einstellungen, Integrationen, Schnittstellen einen Schlüssel an und haken Sie bei den Berechtigungen Changes aus einer Pipeline melden an (Legt Change-Vorgänge aus einer Bau-Pipeline an (POST /api/pipeline/changes)). Mehr braucht die Pipeline nicht. Die Einzelschritte stehen in API-Schlüssel anlegen. Der Schlüssel wird nur einmal angezeigt.

Hinterlegen Sie ihn als geheime Variable:

• GitLab: Einstellungen, CI/CD, Variablen, KNOOING_API_KEY, mit den Optionen „Mask variable“ und „Protect variable“.
• GitHub: Repository-Secret KNOOING_API_KEY.

Warum nie in die Datei? Ein Schlüssel im Repository ist für jeden lesbar, der das Repository sehen darf, und bleibt in der Historie. Wird er bekannt, widerrufen Sie ihn in knooing. Der Schlüssel sendet die Pipeline im Header X-API-Key.

Schritt 2: Die Service-ID bereitstellen

Der Change gehört zu einem Service. Die ID des Services steht in der Adresse seiner Seite im Service-Katalog (…/service-catalog/<Service-ID>). Hinterlegen Sie sie als Variable KNOOING_SERVICE_ID.

Schritt 3a: GitLab CI

Laden Sie die Vorlage herunter: gitlab-ci-template.yml. Sie enthält die Jobs. Es gibt zwei Wege, sie einzubinden.

Variante 1: Datei im eigenen Repository. Legen Sie die Datei in Ihr Repository, zum Beispiel ins Hauptverzeichnis, und binden Sie sie in Ihre .gitlab-ci.yml ein:

include:
  - local: gitlab-ci-template.yml

variables:
  KNOOING_SERVICE_ID: "<Service-ID>"

Variante 2: direkt von der Website. Ohne eigene Kopie binden Sie die Datei per URL ein:

include:
  - remote: https://www.knooing.com/downloads/pipeline/gitlab-ci-template.yml

variables:
  KNOOING_SERVICE_ID: "<Service-ID>"

Warum lieber eine eigene Kopie? Eine Datei im eigenen Repository ändert sich nur, wenn Sie es wollen, und lässt sich prüfen und anpassen. Die Variante per URL zieht bei jedem Lauf den aktuellen Stand, was bequem ist, aber Änderungen unbemerkt übernimmt.

Die Jobs im Überblick:

| Job | Stufe | Läuft, wenn | Meldet | |---|---|---|---| | knooing-change-open | .pre | Standard-Branch oder geschützter Branch oder Tag | legt den Change an und gibt die Change-ID als dotenv-Artefakt weiter | | knooing-change-status | .post | alle früheren Jobs waren erfolgreich | successful | | knooing-change-status-failed | .post | mindestens ein früherer Job ist fehlgeschlagen | failed |

Feature-Branches legen so keinen Change an. Wollen Sie das ändern, überschreiben Sie rules: im jeweiligen Job.

Wichtig zu den Grenzen: Die Statusjobs werten alle früheren Jobs aus, nicht nur Ihren Deploy-Job. Schlägt nach dem Deployment ein späterer Job fehl, meldet die Vorlage failed, obwohl der Rollout selbst gelungen sein kann. Ist Ihr Deploy-Job manuell (when: manual) oder mit allow_failure: true konfiguriert, kann fälschlich successful gemeldet werden. Binden Sie die Meldung dann mit needs an Ihren Deploy-Job:

knooing-change-status:
  needs: [knooing-change-open, deploy-production]

knooing-change-status-failed:
  needs:
    - job: knooing-change-open
      optional: true
    - deploy-production

Prüfen Sie diese Variante einmal, indem Sie den Deploy-Job absichtlich fehlschlagen lassen. Die genaue Auswertung von when: on_failure zusammen mit needs beschreibt die GitLab-Dokumentation nicht eindeutig.

Schritt 3b: GitHub Actions

Laden Sie die Action herunter: action.yml. Legen Sie die Datei in Ihr Repository unter .github/actions/knooing-change/action.yml. Die Composite Action hat zwei Betriebsarten, mode: open und mode: status, und wird mit uses: ./.github/actions/knooing-change verwendet:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - id: change
        uses: ./.github/actions/knooing-change
        with:
          mode: open
          api-key: ${{ secrets.KNOOING_API_KEY }}
          service-id: "<Service-ID>"
      # ... Ihr Deployment ...
      - if: always()
        uses: ./.github/actions/knooing-change
        with:
          mode: status
          api-key: ${{ secrets.KNOOING_API_KEY }}
          change-id: ${{ steps.change.outputs.change-id }}
          outcome: ${{ job.status == 'success' && 'successful' || 'failed' }}

Auf dem Runner müssen curl und jq vorhanden sein, bei GitHub-gehosteten Runnern sind sie es. Eine kurze Beschreibung aller Felder liegt als README.md bei.

Die Felder

Anlage (mode: open, Job knooing-change-open):

| Feld der API | GitLab-Variable | GitHub-Eingabe | Pflicht | Standard | |---|---|---|---|---| | serviceId | KNOOING_SERVICE_ID | service-id | ja | keiner | | title | KNOOING_CHANGE_TITLE | title | ja | Projekt und Commit | | description | KNOOING_CHANGE_DESCRIPTION | description | ja | Verweis auf den Pipeline-Lauf | | impact | KNOOING_IMPACT | impact | ja, 1 bis 5 | 2 | | urgency | KNOOING_URGENCY | urgency | ja, 1 bis 5 | 2 | | changeClass | KNOOING_CHANGE_CLASS | change-class | ja: standard, normal, emergency | standard | | rollbackPlan | KNOOING_ROLLBACK_PLAN | rollback-plan | nein | leer | | externalKey | KNOOING_EXTERNAL_KEY | external-key | nein | Projekt und Pipeline-Lauf |

Statusmeldung (mode: status, Job knooing-change-status):

| Feld der API | GitLab-Variable | GitHub-Eingabe | Pflicht | Standard | |---|---|---|---|---| | outcome | KNOOING_OUTCOME | outcome | ja: successful, partial, failed, rolled_back | successful | | note | KNOOING_NOTE | note | nein | Verweis auf den Pipeline-Lauf |

Die Basis-Adresse steht in KNOOING_API_URL (GitHub: api-url), Standard ist https://api.knooing.info.

Warum Auswirkung und Dringlichkeit? Sie bestimmen wie bei jedem Vorgang die Priorität. Für Routine-Deployments genügen die Standardwerte.

Die Aufrufe direkt, zum Beispiel mit curl

Wer keine der Vorlagen nutzt, ruft die Schnittstelle selbst auf. Der Schlüssel kommt aus der geheimen Variable:

curl -sS -X POST "https://api.knooing.info/api/pipeline/changes" \
  -H "X-API-Key: $KNOOING_API_KEY" -H "Content-Type: application/json" \
  --data '{
    "serviceId": "<Service-ID>",
    "title": "Deployment beispiel-portal a1b2c3d",
    "description": "Automatisches Deployment aus Pipeline 4711",
    "impact": 2,
    "urgency": 2,
    "changeClass": "standard",
    "externalKey": "gitlab-17-4711"
  }'

Die Antwort lautet 201 mit ticket (Nummer) und changeRecord (mit der ID). Nach dem Deployment melden Sie das Ergebnis:

curl -sS -X POST "https://api.knooing.info/api/pipeline/changes/<Change-ID>/status" \
  -H "X-API-Key: $KNOOING_API_KEY" -H "Content-Type: application/json" \
  --data '{"outcome": "successful", "note": "Pipeline 4711"}'

Schritt 4: Das Ergebnis in knooing prüfen

Öffnen Sie in knooing den angelegten Change, im Beispiel „Deployment beispiel-portal a1b2c3d“. Auf dem Reiter Change steht im Abschnitt Umsetzung der Zeitpunkt und im Abschnitt Ergebnis der Umsetzung das gemeldete Ergebnis. Als Person erscheint die, die den Schlüssel ausgestellt hat.

1

1. 1Umsetzung durch die Pipeline gemeldet

1

1. 1Das gemeldete Ergebnis

Wichtig zu wissen

• Doppelte Läufe: Mit externalKey legt ein wiederholter Lauf derselben Pipeline keinen zweiten Change an. Die Antwort lautet dann 200 mit der ID des bestehenden Datensatzes (changeRecordId), sofern ihn derselbe Schlüssel angelegt hat. Die Vorlagen nutzen diese ID, die Statusmeldung funktioniert also auch beim wiederholten Lauf.
• Nur eigene Changes: Ein Schlüssel kann den Status nur für Changes melden, die er selbst angelegt hat. Sonst antwortet die API mit 404.
• Freigabe: Die Statusmeldung gilt als Umsetzungsnachweis. Für standard und normal verlangt knooing dafür eine bereits erteilte Freigabe (siehe Die Stufen eines Changes nacheinander freigeben). Nur emergency darf zuerst umgesetzt und danach freigegeben werden. Eine laufende Freeze-Periode kann die Meldung ebenfalls abweisen (Change-Freeze-Perioden festlegen).
• Funktionstrennung: Meldet derselbe Schlüssel Anlage und Umsetzung, ist das für Pipelines vorgesehen und kein Verstoß (Funktionstrennung bei Changes).

Warum die Freigabe auch für Pipelines? Automatisierung ändert nichts am Prozess: Ein Normal-Change braucht Peer-Review und CAB, auch wenn ihn eine Maschine ausrollt. Für Routine bietet sich standard mit einer genehmigten Vorlage an (Standard-Change-Vorlage anlegen).

Wenn etwas nicht klappt

Die Vorlagen schreiben Fehler als HTTP-Status mit Meldung und Fehlercode ins Job-Protokoll:

• Anlage fehlgeschlagen (HTTP 401): Ungültiger oder fehlender API-Schlüssel. [unauthorized] Der Schlüssel in KNOOING_API_KEY stimmt nicht, ist widerrufen oder abgelaufen.
• Anlage fehlgeschlagen (HTTP 400): impact und urgency müssen zwischen 1 und 5 liegen. [validation] Ein Feld ist ungültig. Weitere Meldungen dieser Art: serviceId ist Pflicht., title ist Pflicht., description ist Pflicht. und changeClass ist Pflicht (standard/normal/emergency).
• Anlage fehlgeschlagen (HTTP 404): Service nicht gefunden. [service_not_found] Die Service-ID stimmt nicht.
• Statusmeldung fehlgeschlagen (HTTP 409): Die Umsetzung setzt die erteilte Freigabe voraus - nachgelagert zulässig ist das nur bei einem Notfall-Change. [conflict] Der Change ist noch nicht freigegeben. Lassen Sie ihn freigeben oder melden Sie den Status später.
• Statusmeldung fehlgeschlagen (HTTP 404): Change-Datensatz nicht gefunden. [not_found] Die Change-ID passt nicht oder gehört zu einem anderen Schlüssel.
• Statusmeldung fehlgeschlagen (HTTP 400): outcome ist Pflicht und muss eines von successful, partial, failed, rolled_back sein. [validation] Das Ergebnis hat einen ungültigen Wert.
• Change mit diesem externalKey existiert bereits … es wurde nichts angelegt. Das ist kein Fehler, der Lauf ist ein Wiederholer.
• Die Statusmeldung bleibt aus. Ohne Change-ID meldet der Job keine Change-ID vorhanden (Change wurde nicht neu angelegt), Status wird nicht gemeldet. und beendet sich. Prüfen Sie den Open-Job.

Alles zu dieser Anforderung finden Sie auch über die Suche: A1-34.