Skip to main content
Wir veröffentlichen regelmäßig Aktualisierungen unserer Dokumentation, und die Übersetzung dieser Seite ist möglicherweise noch nicht abgeschlossen. Aktuelle Informationen findest du in der englischsprachigen Dokumentation.
All products
GitHub Actions

Verwenden der GitHub CLI auf einem Runner

In diesem Artikel

Verwenden erweiterter GitHub Actions-Features für Continuous Integration (CI).

Hinweis: GitHub-gehostete Runner werden auf GitHub Enterprise Server derzeit nicht unterstützt. Weitere Informationen zur geplanten zukünftigen Unterstützung findest Du in der GitHub public roadmap.

Ü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:

FeatureImplementierung
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 "::set-output name=title::$(head -1 broken_links.md)"
      - 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 "::set-output name=title::$(head -1 broken_links.md)"

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