Verwenden der GitHub CLI auf einem Runner

Übersicht über das Beispiel

In diesem Artikel werden anhand eines Beispielworkflows einige der wichtigsten CI-Features von GitHub Actions vorgestellt. Wenn dieser Workflow ausgelöst wird, wird automatisch ein Skript ausgeführt, das überprüft, ob die GitHub-Docs-Website fehlerhafte Links aufweist. Wenn fehlerhafte Links gefunden werden, verwendet der Workflow die GitHub CLI, um ein GitHub-Issue mit den Details zu erstellen.

Das folgende Diagramm zeigt die allgemeinen Schritte im Workflow und wie sie im Auftrag ausgeführt werden:

Übersichtsdiagramm der Workflowschritte

In diesem Beispiel verwendete Features

Der Beispielworkflow veranschaulicht die folgenden Möglichkeiten von GitHub Actions.

Feature	Implementierung
Ausführen eines Workflows in regelmäßigen Abständen	`schedule`

Beispielworkflow

Der folgende Workflow wurde von dem Docs Engineering-Team für GitHub erstellt. Um die neueste Version dieser Datei im Repository github/docs zu überprüfen, siehe check-all-english-links.yml.

Hinweis: Jede Zeile dieses Workflows wird im nächsten Abschnitt unter Grundlegendes zum Beispiel erläutert.

YAML

name: Check all English links

# **What it does**: This script once a day checks all English links and reports in issues.
# **Why we have it**: We want to know if any links break.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  schedule:
    - cron: '40 19 * * *' # once a day at 19:40 UTC / 11:40 PST

permissions:
  contents: read
  issues: write

jobs:
  check_all_english_links:
    name: Check all links
    if: github.repository == 'github/docs-internal'
    runs-on: ubuntu-latest
    env:
      GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }}
      FIRST_RESPONDER_PROJECT: Docs content first responder
      REPORT_AUTHOR: docubot
      REPORT_LABEL: broken link report
      REPORT_REPOSITORY: github/docs-content
    steps:
      - name: Check out repo's default branch
        uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm
      - name: npm ci
        run: npm ci
      - name: npm run build
        run: npm run build
      - name: Run script
        run: |
          script/check-english-links.js > broken_links.md

      # check-english-links.js returns 0 if no links are broken, and 1 if any links
      # are broken. When an Actions step's exit code is 1, the action run's job status
      # is failure and the run ends. The following steps create an issue for the
      # broken link report only if any links are broken, so `if: ${{ failure() }}`
      # ensures the steps run despite the previous step's failure of the job.

      - if: ${{ failure() }}
        name: Get title for issue
        id: check
        run: echo "title=$(head -1 broken_links.md)" >> $GITHUB_OUTPUT
      - if: ${{ failure() }}
        name: Create issue from file
        id: broken-link-report
        uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e
        with:
          token: ${{ env.GITHUB_TOKEN }}

          title: ${{ steps.check.outputs.title }}
          content-filepath: ./broken_links.md
          repository: ${{ env.REPORT_REPOSITORY }}
          labels: ${{ env.REPORT_LABEL }}
      - if: ${{ failure() }}
        name: Close and/or comment on old issues
        env:
          NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}'
        run: |
          gh alias set list-reports "issue list \
                                       --repo ${{ env.REPORT_REPOSITORY }} \
                                       --author ${{ env.REPORT_AUTHOR }} \
                                       --label '${{ env.REPORT_LABEL }}'"

          # Link to the previous report from the new report that triggered this
          # workflow run.

          previous_report_url=$(gh list-reports \
                                  --state all \
                                  --limit 2 \
                                  --json url \
                                  --jq '.[].url' \
                                  | grep -v ${{ env.NEW_REPORT_URL }} | head -1)

          gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"

          # If an old report is open and assigned to someone, link to the newer
          # report without closing the old report.

          for issue_url in $(gh list-reports \
                                  --json assignees,url \
                                  --jq '.[] | select (.assignees != []) | .url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
            fi
          done

          # Link to the newer report from any older report that is still open,
          # then close the older report and remove it from the first responder's
          # project board.

          for issue_url in $(gh list-reports \
                                  --search 'no:assignee' \
                                  --json url \
                                  --jq '.[].url'); do
            if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then
              gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})"
              gh issue close $issue_url
              gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}"
            fi
          done

Grundlegendes zum Beispiel

In der folgenden Tabelle wird erläutert, wie jedes dieser Features beim Erstellen eines GitHub Actions-Workflows verwendet wird.

Code	Erklärung
YAML `name: Check all English links`	Der Name des Workflows, der auf der Registerkarte „Aktionen“ im GitHub-Repository angezeigt wird.
YAML `on: workflow_dispatch: schedule: - cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST`	Definiert `workflow_dispatch` und `scheduled` als Trigger für den Workflow: Mit `workflow_dispatch` kannst du diesen Workflow manuell von der Benutzeroberfläche aus ausführen. Weitere Informationen findest du unter `workflow_dispatch`. Mit dem `schedule`-Ereignis kannst du mithilfe der `cron`-Syntax ein reguläres Intervall definieren, um den Workflow automatisch auszulösen. Weitere Informationen findest du unter `schedule`.
YAML `permissions: contents: read issues: write`	Ändert die für `GITHUB_TOKEN` gewährten Standardberechtigungen. Dies variiert je nach den Anforderungen deines Workflows. Weitere Informationen findest du unter Zuweisen von Berechtigungen zu Aufträgen.
YAML `jobs:`	Gruppiert alle in der Workflowdatei ausgeführten Aufträge.
YAML `check_all_english_links: name: Check all links`	Definiert einen Auftrag mit der ID `check_all_english_links` und dem Namen `Check all links`, die innerhalb des `jobs`-Schlüssels gespeichert sind.
YAML `if: github.repository == 'github/docs-internal'`	Führe den `check_all_english_links`-Auftrag nur aus, wenn das Repository `docs-internal` heißt und sich innerhalb der Organisation `github` befindet. Andernfalls wird der Auftrag als übersprungen markiert.
YAML `runs-on: ubuntu-latest`	Konfiguriert den Auftrag, der auf einem Ubuntu Linux-Runner ausgeführt werden soll. Dies bedeutet, dass der Auftrag auf einer neuen, von GitHub gehosteten VM ausgeführt wird. Syntaxbeispiele mit anderen Runnern findest du unter Workflowsyntax für GitHub Actions.
YAML `env: GITHUB_TOKEN: ${{ secrets.DOCUBOT_READORG_REPO_WORKFLOW_SCOPES }} REPORT_AUTHOR: docubot REPORT_LABEL: broken link report REPORT_REPOSITORY: github/docs-content`	Erstellt benutzerdefinierte Umgebungsvariablen und definiert die integrierte `GITHUB_TOKEN`-Variable neu, um ein benutzerdefiniertes Geheimnis zu verwenden. Auf diese Variablen wird später im Workflow verwiesen.
YAML `steps:`	Gruppiert alle Schritte, die als Teil des `check_all_english_links`-Auftrags ausgeführt werden. Jeder Auftrag im Workflow verfügt über einen eigenen `steps`-Abschnitt.
YAML `- name: Check out repo's default branch uses: actions/checkout@v3`	Das `uses`-Schlüsselwort weist den Auftrag an, die Aktion mit dem Namen `actions/checkout` abzurufen. Mit dieser Aktion wird dein Repository ausgecheckt und in den Runner heruntergeladen. Dadurch kannst du Aktionen für deinen Code ausführen (z. B. Testtools). Du musst die Auscheckaktion jedes Mal verwenden, wenn dein Workflow mit dem Code des Repositorys ausgeführt wird, oder du eine im Repository definierte Aktion verwendest.
YAML `- name: Setup Node uses: actions/setup-node@v3 with: node-version: 16.8.x cache: npm`	In diesem Schritt wird mit der `actions/setup-node`-Aktion die angegebene Version des `node`-Softwarepakets auf dem Runner installiert. Dadurch erhältst du Zugriff auf den `npm`-Befehl.
YAML `- name: Run the "npm ci" command run: npm ci - name: Run the "npm run build" command run: npm run build`	Mit dem `run`-Schlüsselwort wird der Auftrag angewiesen, einen Befehl im Runner auszuführen. In diesem Fall werden die Befehle `npm ci` und `npm run build` als separate Schritte zum Installieren und Erstellen der Node.js-Anwendung im Repository ausgeführt.
YAML `- name: Run script run: \| script/check-english-links.js > broken_links.md`	Dieser `run`-Befehl führt ein Skript aus, das im Repository unter `script/check-english-links.js` gespeichert ist, und reicht die Ausgabe an eine Datei namens `broken_links.md` weiter.
YAML `- if: ${{ failure() }} name: Get title for issue id: check run: echo "title=$(head -1 broken_links.md)" >> $GITHUB_OUTPUT`	Wenn das `check-english-links.js`-Skript fehlerhafte Verknüpfungen erkennt und einen Nicht-Null (0)-Status (Fehler) zurückgibt, lege mit einem Workflowbefehl eine Ausgabe fest, die den Wert der ersten Zeile der `broken_links.md`-Datei hat (wird im nächsten Schritt verwendet).
YAML `- if: ${{ failure() }} name: Create issue from file id: broken-link-report uses: peter-evans/create-issue-from-file@b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e with: token: ${{ env.GITHUB_TOKEN }} title: ${{ steps.check.outputs.title }} content-filepath: ./broken_links.md repository: ${{ env.REPORT_REPOSITORY }} labels: ${{ env.REPORT_LABEL }}`	Erstellt mit der `peter-evans/create-issue-from-file`-Aktion ein neues GitHub-Issue. Dieses Beispiel wird mit `b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e`-SHA einer bestimmten Version der Aktion angeheftet.
YAML - if: ${{ failure() }} name: Close and/or comment on old issues env: NEW_REPORT_URL: 'https://github.com/${{ env.REPORT_REPOSITORY }}/issues/${{ steps.broken-link-report.outputs.issue-number }}' run: \| gh alias set list-reports "issue list \ --repo ${{ env.REPORT_REPOSITORY }} \ --author ${{ env.REPORT_AUTHOR }} \ --label '${{ env.REPORT_LABEL }}'" previous_report_url=$(gh list-reports \ --state all \ --limit 2 \ --json url \ --jq '.[].url' \ \| grep -v ${{ env.NEW_REPORT_URL }} \| head -1) gh issue comment ${{ env.NEW_REPORT_URL }} --body "⬅️ [Previous report]($previous_report_url)"	Sucht mit `gh issue list` das zuvor erstellte Issue aus früheren Ausführungen. Dies erhält zur einfacheren Verarbeitung in späteren Schritten den Alias `gh list-reports`. Um die Issue-URL abzurufen, verarbeitet der `jq`-Ausdruck die resultierende JSON-Ausgabe. Dann wird mit `gh issue comment` dem neuen Issue ein Kommentar hinzugefügt, der die Verknüpfung mit dem vorherigen herstellt.
YAML `for issue_url in $(gh list-reports \ --json assignees,url \ --jq '.[] \| select (.assignees != []) \| .url'); do if [ "$issue_url" != "$" ]; then gh issue comment $issue_url --body "➡️ [Newer report]($)" fi done`	Wenn ein Issue aus einer vorherigen Ausführung geöffnet und jemandem zugewiesen ist, füge mit `gh issue comment` einen Kommentar mit einem Link zum neuen Issue hinzu.
YAML `for issue_url in $(gh list-reports \ --search 'no:assignee' \ --json url \ --jq '.[].url'); do if [ "$issue_url" != "${{ env.NEW_REPORT_URL }}" ]; then gh issue comment $issue_url --body "➡️ [Newer report](${{ env.NEW_REPORT_URL }})" gh issue close $issue_url gh issue edit $issue_url --remove-project "${{ env.FIRST_RESPONDER_PROJECT }}" fi done`	Wenn ein Issue aus einer vorherigen Ausführung geöffnet und niemandem zugewiesen ist, dann: Füge mit `gh issue comment` einen Kommentar mit einem Link zum neuen Issue hinzu. Schließe das alte Issue mit `gh issue close`. Bearbeite das alte Issue mit `gh issue edit`, um es aus einem bestimmten GitHub-Projektboard zu entfernen.

Nächste Schritte

Informationen zu GitHub Actions-Konzepten findest du unter Grundlegendes zu GitHub Actions.
Weitere schrittweise Anleitungen zum Erstellen eines einfachen Workflows findest du unter Schnellstart für GitHub Actions.
Wenn du mit den Grundlagen von GitHub Actions vertraut bist, erfährst du unter Informationen zu Workflows mehr über Workflows und deren Features.