Using the GitHub CLI on a runner

ノート: GitHubホストランナーは、現在GitHub Enterprise Serverでサポートされていません。 GitHubパブリックロードマップで、計画されている将来のサポートに関する詳しい情報を見ることができます。

Example overview

この記事では、サンプルのワークフローを使ってGitHub ActionsのCIの主な機能の一部を紹介しています。 When this workflow is triggered, it automatically runs a script that checks whether the GitHub Docs site has any broken links. If any broken links are found, the workflow uses the GitHub CLI to create a GitHub issue with the details.

以下の図は、ワークフローのステップとそれらがジョブの中で実行される様子を、高レベルの視点から描いています。

Overview diagram of workflow steps

Features used in this example

サンプルのワークフローは、GitHub Actionsの以下の機能を紹介しています:

機能	Implementation

定期的な間隔でワークフローを実行:	`schedule`
トークンの権限を設定:	`permissions`
特定の条件を満たさないかぎりジョブを実行しないようにする:	`if`
ワークフロー内のシークレットを参照します:	Secrets
リポジトリをランナーにクローン:	`actions/checkout`
`ノード`をランナーにインストール:	`actions/setup-node`
Using a third-party action:	`peter-evans/create-issue-from-file`

ワークフローの例

以下のワークフローは、GitHub Docs Engineeringチームが作成しました。 github/docsリポジトリ内のこのファイルの最新バージョンをレビューするには、次を参照してください。 check-all-english-links.yml.

ノート: このワークフローの各行は「例を理解する」の次のセクションで説明されています。

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@v2
      - name: Setup Node
        uses: actions/setup-node@v2
        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

Understanding the example

以下の表は、これらの機能がそれぞれGitHub Actionsワークフローの作成時にどのように使われるかを説明しています。

コード	Explanation
YAML `name: Check all English links`	GitHubリポジトリの"Actions"タブに表示されるワークフローの名前。
YAML `on: workflow_dispatch: schedule: - cron: '40 20 * * *' # once a day at 20:40 UTC / 12:40 PST`	Defines the `workflow_dispatch` and `scheduled` as triggers for the workflow: The `workflow_dispatch` lets you manually run this workflow from the UI. For more information, see `workflow_dispatch`. The `schedule` event lets you use `cron` syntax to define a regular interval for automatically triggering the workflow. For more information, see `schedule`.
YAML `permissions: contents: read issues: write`	Modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "Assigning permissions to jobs."
YAML `jobs:`	Groups together all the jobs that run in the workflow file.
YAML `check_all_english_links: name: Check all links`	Defines a job with the ID `check_all_english_links`, and the name `Check all links`, that is stored within the `jobs` key.
YAML `if: github.repository == 'github/docs-internal'`	Only run the `check_all_english_links` job if the repository is named `docs-internal` and is within the `github` organization. Otherwise, the job is marked as skipped.
YAML `runs-on: ubuntu-latest`	Ubuntu Linux ランナーで実行するようにジョブを設定します。 This means that the job will execute on a fresh virtual machine hosted by GitHub. For syntax examples using other runners, see "Workflow syntax for 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`	Creates custom environment variables, and redefines the built-in `GITHUB_TOKEN` variable to use a custom secret. These variables will be referenced later in the workflow.
YAML `steps:`	Groups together all the steps that will run as part of the `check_all_english_links` job. Each job in the workflow has its own `steps` section.
YAML `- name: Check out repo's default branch uses: actions/checkout@v2`	The `uses` keyword tells the job to retrieve the action named `actions/checkout`. これは、リポジトリをチェックアウトしてランナーにダウンロードし、コードに対してアクション（テストツールなど）を実行できるようにします。ワークフローがリポジトリのコードに対して実行されるとき、またはリポジトリで定義されたアクションを使用しているときはいつでも、チェックアウトアクションを使用する必要があります。
YAML `- name: Setup Node uses: actions/setup-node@v2 with: node-version: 16.8.x cache: npm`	This step uses the `actions/setup-node` action to install the specified version of the `node` software package on the runner, which gives you access to the `npm` command.
YAML `- name: Run the "npm ci" command run: npm ci - name: Run the "npm run build" command run: npm run build`	The `run` keyword tells the job to execute a command on the runner. In this case, the `npm ci` and `npm run build` commands are run as separate steps to install and build the Node.js application in the repository.
YAML `- name: Run script run: \| script/check-english-links.js > broken_links.md`	This `run` command executes a script that is stored in the repository at `script/check-english-links.js`, and pipes the output to a file called `broken_links.md`.
YAML `- if: ${{ failure() }} name: Get title for issue id: check run: echo "::set-output name=title::$(head -1 broken_links.md)"`	If the `check-english-links.js` script detects broken links and returns a non-zero (failure) exit status, then use a workflow command to set an output that has the value of the first line of the `broken_links.md` file (this is used the next step).
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 }}`	Uses the `peter-evans/create-issue-from-file` action to create a new GitHub issue. This example is pinned to a specific version of the action, using the `b4f9ee0a9d4abbfc6986601d9b1a4f8f8e74c77e` SHA.
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)"	Uses `gh issue list` to locate the previously created issue from earlier runs. This is aliased to `gh list-reports` for simpler processing in later steps. To get the issue URL, the `jq` expression processes the resulting JSON output. `gh issue comment` is then used to add a comment to the new issue that links to the previous one.
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`	If an issue from a previous run is open and assigned to someone, then use `gh issue comment` to add a comment with a link to the new issue.
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`	If an issue from a previous run is open and is not assigned to anyone, then: Use `gh issue comment` to add a comment with a link to the new issue. Use `gh issue close` to close the old issue. Use `gh issue edit` to edit the old issue to remove it from a specific GitHub project board.

次のステップ

GitHub Actionsの概念について学ぶには、「GitHub Actionsを理解する」を参照してください。
基本的なワークフローを作成するためのステップバイステップのガイドについては「GitHub Actionsのクイックスタート」を参照してください。
GitHub Actionsの基本に慣れたなら、ワークフローとその機能について「ワークフローについて」で学べます。