Pipeline – Manuelle Workflow-Genehmigung

Pausieren Sie einen STACKIT Git Actions-Workflow und fordern Sie eine manuelle Genehmigung von einer oder mehreren genehmigenden Personen an, bevor Sie fortfahren.

Dies ist eine gängige Funktion für eine Deployment- oder Release-Pipeline.

Hinweis: Diese Genehmigungsdauer unterliegt dem allgemeineren Timeout von 4 Stunden für einen Workflow sowie den Nutzungskosten. Behalten Sie dies im Hinterkopf, wenn Sie festlegen, wie schnell eine genehmigende Person reagieren muss. Siehe Einschränkungen für weitere Informationen.

Hinweis: Eine kostengünstigere, aber weniger automatische Lösung mit geteilten Jobs und dem Workflow-Dispatcher finden Sie hier.

Diese Action funktioniert wie folgt:

1. Der Workflow erreicht die manual-approval-Action.
2. manual-approval erstellt ein Issue im entsprechenden Repository und weist es den approvers zu.
3. Wenn und sobald alle genehmigenden Personen mit einem Schlüsselwort für die Genehmigung antworten, wird der Workflow fortgesetzt.
4. Wenn eine der genehmigenden Personen mit einem Schlüsselwort für eine Ablehnung antwortet, wird der Workflow mit einem fehlgeschlagenen Status beendet.
   • Schlüsselwörter für eine Genehmigung – „approve“, „approved“, „lgtm“, „yes“
   • Schlüsselwörter für eine Ablehnung – „deny“, „denied“, „no“

Bei diesen Schlüsselwörtern wird nicht zwischen Groß- und Kleinschreibung unterschieden. Zudem können sie optionale Satzzeichen wie einen Punkt oder ein Ausrufezeichen enthalten.

In allen Fällen schließt manual-approval das ursprüngliche StackitGit-Issue.

Verwendung

steps:
  - uses: [https://stackit.git.onstackit.cloud/actions/manual-approval@v1](https://stackit.git.onstackit.cloud/actions/manual-approval@v1)
    with:
      secret: ${{ github.TOKEN }}
      approvers: user1,user2,org-team1
      minimum-approvals: 1
      issue-title: "Deploying v1.3.5 to prod from staging"
      issue-body: "Please approve or deny the deployment of version v1.3.5."
      issue-body-file-path: relative/file_path/wrt/repo/root
      exclude-workflow-initiator-as-approver: false
      fail-on-denial: true
      additional-approved-words: ""
      additional-denied-words: ""
      polling-interval-seconds: 10

• approvers ist eine durch Kommata getrennte Liste aller erforderlichen genehmigenden Personen. Eine genehmigende Person kann entweder ein Benutzer oder ein Organisationsteam sein. (Hinweis: Erforderliche genehmigende Personen müssen berechtigt sein, als genehmigende Personen im Repository festgelegt zu werden. Wenn Sie eine genehmigende Person hinzufügen, die nicht über diese Berechtigung verfügt, erhalten Sie beim Ausführen dieser Action den Fehler „HTTP/402 Validation Failed“.)
• minimum-approvals ist eine Ganzzahl, welche die Mindestanzahl der erforderlichen Genehmigungen festlegt, um den Workflow fortzusetzen. Standardmäßig sind ALLE genehmigenden Personen erforderlich.
• issue-title ist ein String, der als Titel des Genehmigungs-Issues verwendet wird.
• issue-body ist ein String, der als Kommentar zum Genehmigungs-Issue hinzugefügt wird.
• issue-body-file-path ist ein String, der den Dateipfad angibt. Der Inhalt dieser Datei wird als Kommentar zum Genehmigungs-Issue hinzugefügt. Wenn sowohl issue-body als auch issue-body-file-path angegeben sind, wird der Dateiinhalt für die Issue-Kommentare herangezogen.
• exclude-workflow-initiator-as-approver ist ein Boolean, der angibt, ob der Initiator des Workflows (bestimmt durch die Umgebungsvariable GITHUB_ACTOR) aus der finalen Liste der genehmigenden Personen herausgefiltert werden soll. Dies ist optional und hat den Standardwert false. Setzen Sie diesen Wert auf true, um zu verhindern, dass Benutzer in der approvers-Liste ihre eigenen Workflows selbst genehmigen können.
• fail-on-denial ist a Boolean, der angibt, ob der Workflow fehlschlagen soll, wenn eine genehmigende Person die Genehmigung ablehnt. Dies ist optional und hat den Standardwert true. Setzen Sie diesen Wert auf false, damit der Workflow fortgesetzt werden kann, auch wenn eine genehmigende Person die Genehmigung ablehnt.
• additional-approved-words ist eine durch Kommata getrennte Liste von Strings, um das Wörterbuch der Wörter zu erweitern, die eine Genehmigung anzeigen. Dies ist optional und standardmäßig ein leerer String.
• additional-denied-words ist eine durch Kommata getrennte Liste von Strings, um das Wörterbuch der Wörter zu erweitern, die eine Ablehnung anzeigen. Dies ist optional und standardmäßig ein leerer String.
• polling-interval-seconds ist eine Ganzzahl, welche die Anzahl der Sekunden festlegt, die zwischen den Abfragen der StackitGit-API bezüglich des Genehmigungsstatus gewartet werden soll. Dies ist optional und beträgt standardmäßig 10 Sekunden. Erhöhen Sie diesen Wert, wenn Sie die Anzahl der API-Aufrufe reduzieren möchten, oder verringern Sie ihn für schnellere Reaktionszeiten.

Hinweis:

1. Wenn Sie issue-body-file-path verwenden, stellen Sie bitte sicher, dass die Datei erreichbar ist. Wenn sich die Datei beispielsweise in Ihrem Repository befindet, checken Sie Ihr Repository im selben Job aus wie das Genehmigungs-Issue.
2. Bei der Verwendung von issue-body wird der Inhalts-String als Argument übergeben, das von StackitGit auf 10 KB beschränkt ist. Verwenden Sie für Inhalte von mehr als oder gleich 10 KB Dateien, um den Issue-Body zu übergeben.

ACHTUNG: Wenn Sie eine Datei verwenden, stellen Sie bitte sicher, dass die Dateigröße unter 125 KB bleibt (ein sicherer Grenzwert, um unter dem Schwellenwert zu bleiben). Wenn die Datei riesig ist, wird ihr Inhalt in mehrere Teile zerlegt, von denen jeder einen Issue-Kommentar darstellt. Bei so vielen API-Anfragen wird das API-Rate-Limit überschritten und die Actions werden vorübergehend blockiert, was zu einer Fehlermeldung wie dieser führt: 403 You have exceeded a secondary rate limit and have been temporarily blocked from content creation. Please retry your request again later. 5 MB ist eine grobe Schätzung, da sekundäre Rate-Limits für einen Benutzer gelten. Ihr Benutzer (in der Regel der Bot, der ein App-Token zur Authentifizierung verwendet) kann daher für einige Zeit keine Aktionen ausführen. Primäre Limits werden möglicherweise schnell zurückgesetzt, sekundäre Limits benötigen jedoch eine gewisse Abkühlzeit.

Die Dateimethode funktioniert, es sei denn, die Datei selbst ist so groß, dass sie nach dem Aufteilen in Teile von 65.000 Zeichen das API-Limit überschreitet.

Outputs

• approval-status ist ein String, der den finalen Status der Genehmigung angibt. Dieser ist entweder approved oder denied.

Issues in einem anderen Repository erstellen

steps:
  - uses: [https://stackit.git.onstackit.cloud/actions/manual-approval@v1](https://stackit.git.onstackit.cloud/actions/manual-approval@v1)
    with:
      secret: ${{ github.TOKEN }}
      approvers: user1,user2,org-team1
      minimum-approvals: 1
      issue-title: "Deploying v1.3.5 to prod from staging"
      issue-body: "Please approve or deny the deployment of version v1.3.5."
      exclude-workflow-initiator-as-approver: false
      additional-approved-words: ""
      additional-denied-words: ""
      target-repository: repository-name
      target-repository-owner: owner-id

• Wenn entweder target-repository oder target-repository-owner fehlt oder ein leerer String ist, wird das Issue in demselben Repository erstellt, in dem dieser Schritt verwendet wird.

Eigene Wörter verwenden

STACKIT Git verfügt über eine umfangreiche Bibliothek an Emojis, die alle in den zusätzlichen genehmigten oder abgelehnten Wörtern funktionieren. Einige Werte speichert StackitGit in ihrer Textversion – mit anderen Worten :shipit:. Andere Emojis speichert StackitGit in ihrer Unicode-Emoji-Form, wie ✅. Für eine nahtlose Bereitstellung wird empfohlen, die benutzerdefinierten Wörter zu einem StackitGit-Kommentar hinzuzufügen und sie dann aus dem Kommentar zurück in Ihre Actions-Konfigurations-YAML zu kopieren.

Organisationsteam als genehmigende Person

Wenn Sie approvers auf ein Organisationsteam festlegen möchten, müssen Sie einen anderen Ansatz wählen. Das standardmäßige automatische Token für STACKIT Git Actions verfügt nicht über die erforderlichen Berechtigung, um Teammitglieder aufzulisten. Wenn Sie dies nutzen möchten, müssen Sie ein Token über eine STACKIT Git App mit den korrekten Berechtigungen generieren. Abgesehen davon benötigt die StackitGit App auch die Rolle Issue: Read & Write.

Erstellen Sie eine Organisations-StackitGit App mit lesendem Zugriff auf Organisationsmitglieder (read-only access to organization members). Sobald die App erstellt ist, fügen Sie ein Repository-Secret mit der App-ID hinzu. Generieren Sie in den Einstellungen der StackitGit App einen privaten Schlüssel und fügen Sie diesen ebenfalls als Secret im Repository hinzu. Sie können das App-Token über die StackitGit Action actions/create-github-app-token abrufen:

Hinweis: Die Token der StackitGit App laufen nach 1 Stunde ab. Das bedeutet, dass die Dauer für die Genehmigung 60 Minuten nicht überschreiten darf, da der Job andernfalls aufgrund ungültiger Zugangsdaten fehlschlägt. Siehe Dokumentation.

jobs:
  myjob:
    runs-on: ubuntu-latest
    steps:
      - name: Generate token
        id: generate_token
        uses: actions/create-github-app-token@v2
        with:
          app-id: ${{ secrets.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
      - name: Wait for approval
        uses: [https://stackit.git.onstackit.cloud/actions/manual-approval@v1](https://stackit.git.onstackit.cloud/actions/manual-approval@v1)
        with:
          secret: ${{ steps.generate_token.outputs.token }}
          approvers: myteam
          minimum-approvals: 1

Timeout

Wenn Sie ein Timeout für Ihre Workflow-Pause erzwingen möchten, können Sie timeout-minutes entweder auf Schritt-Ebene oder auf Job-Ebene angeben.

Hinweis: Die Option timeout-minutes wurde aus den Inputs von manual-approval entfernt, da sie keine Funktion hatte und Benutzern fälschlicherweise zusicherte, dass sie tatsächlich ein Timeout-Verhalten erhielten. Bitte verwenden Sie stattdessen einen der folgenden zwei Ansätze. Wenn Sie timeout-minutes derzeit als Input für manual-approval verwenden, wird möglicherweise eine Warnung angezeigt, die Ihre Action jedoch nicht beeinträchtigt.

Wenn Sie beispielsweise möchten, dass Ihr manueller Genehmigungsschritt nach einer Stunde ein Timeout auslöst, können Sie Folgendes tun:

jobs:
  approval:
    steps:
      - uses: https://stackit.git.onstackit.cloud/actions/manual-approval@v1
        timeout-minutes: 60
    # ...

oder

jobs:
  approval:
    timeout-minutes: 10
    steps:
      - uses: https://stackit.git.onstackit.cloud/actions/manual-approval@v1

Einschränkungen

• Während der Workflow pausiert ist, verbraucht er weiterhin eine Zuweisung für gleichzeitige Jobs aus dem maximalen Kontingent von 20 gleichzeitigen Jobs.
• Ein pausierter Job führt weiterhin Berechnungen auf der Instanz oder der virtuellen Maschine aus, sodass fortlaufend Kosten anfallen.
• Ablauf (wird auch an anderer Stelle in diesem Dokument erwähnt):
  • Ein Job (einschließlich eines pausierten Jobs) schlägt nach 4 Stunden fehl, und ein Workflow schlägt nach 35 Tagen fehl.
  • Token der StackitGit App laufen nach 1 Stunde ab. Das bedeutet, dass die Dauer für die Genehmigung 60 Minuten nicht überschreiten darf, da der Job andernfalls aufgrund ungültiger Zugangsdaten fehlschlägt.