Using scripts to test your code on a runner

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.

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

Overview diagram of workflow steps

Features used in this example

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

機能	Implementation

自動的に実行されるワークフローのトリガー:	`push`
自動的に実行されるワークフローのトリガー:	`pull_request`
UIからワークフローを手動で実行:	`workflow_dispatch`
トークンの権限を設定:	`permissions`
同時に実行できるワークフローの実行もしくはジョブ数を制御:	`concurrency`
Running the job on different runners, depending on the repository:	`runs-on`
リポジトリをランナーにクローン:	`actions/checkout`
`ノード`をランナーにインストール:	`actions/setup-node`
Using a third-party action:	`trilom/file-changes-action`

ワークフローの例

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

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

YAML

name: 'Link Checker: All English'

# **What it does**: Renders the content of every page and check all internal links.
# **Why we have it**: To make sure all links connect correctly.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:

permissions:
  contents: read
  # Needed for the 'trilom/file-changes-action' action
  pull-requests: read

# This allows a subsequently queued workflow run to interrupt previous runs
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

jobs:
  check-links:
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Setup node
        uses: actions/setup-node@v3
        with:
          node-version: 16.13.x
          cache: npm

      - name: Install
        run: npm ci

      # Creates file "$/files.json", among others
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

      # For verification
      - name: Show files changed
        run: cat $HOME/files.json

      - name: Link check (warnings, changed files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --max 100 \
            --check-anchors \
            --check-images \
            --verbose \
            --list $HOME/files.json

      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

Understanding the example

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

コード	Explanation
YAML `name: 'Link Checker: All English'`	GitHubリポジトリの"Actions"タブに表示されるワークフローの名前。
YAML `on:`	The `on` keyword lets you define the events that trigger when the workflow is run. You can define multiple events here. For more information, see "Triggering a workflow."
YAML `workflow_dispatch:`	Add the `workflow_dispatch` event if you want to be able to manually run this workflow from the UI. For more information, see `workflow_dispatch`.
YAML `push: branches: - main`	Add the `push` event, so that the workflow runs automatically every time a commit is pushed to a branch called `main`. For more information, see `push`.
YAML `pull_request:`	Add the `pull_request` event, so that the workflow runs automatically every time a pull request is created or updated. For more information, see `pull_request`.
YAML `permissions: contents: read pull-requests: read`	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 `concurrency: group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label \|\| github.head_ref \|\| github.ref }}'`	Creates a concurrency group for specific events, and uses the `\|\|` operator to define fallback values. For more information, see "Using concurrency."
YAML `cancel-in-progress: true`	Cancels any currently running job or workflow in the same concurrency group.
YAML `jobs:`	Groups together all the jobs that run in the workflow file.
YAML `check-links:`	Defines a job with the ID `check-links` that is stored within the `jobs` key.
YAML `runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}`	Configures the job to run on a GitHub-hosted runner or a self-hosted runner, depending on the repository running the workflow. In this example, the job will run on a self-hosted runner if the repository is named `docs-internal` and is within the `github` organization. If the repository doesn't match this path, then it will run on an `ubuntu-latest` runner hosted by GitHub. For more information on these options see "Choosing the runner for a job."
YAML `steps:`	Groups together all the steps that will run as part of the `check-links` job. Each job in a workflow has its own `steps` section.
YAML `- name: Checkout uses: actions/checkout@v3`	The `uses` keyword tells the job to retrieve the action named `actions/checkout`. これは、リポジトリをチェックアウトしてランナーにダウンロードし、コードに対してアクション（テストツールなど）を実行できるようにします。ワークフローがリポジトリのコードに対して実行されるとき、またはリポジトリで定義されたアクションを使用しているときはいつでも、チェックアウトアクションを使用する必要があります。
YAML `- name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm`	This step uses the `actions/setup-node` action to install the specified version of the Node.js software package on the runner, which gives you access to the `npm` command.
YAML `- name: Install run: npm ci`	The `run` keyword tells the job to execute a command on the runner. In this case, `npm ci` is used to install the npm software packages for the project.
YAML `- name: Gather files changed uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b with: fileOutput: 'json'`	Uses the `trilom/file-changes-action` action to gather all the changed files. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
YAML `- name: Show files changed run: cat $HOME/files.json`	Lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging.
YAML `- name: Link check (warnings, changed files) run: \| ./script/rendered-content-link-checker.mjs \ --language en \ --max 100 \ --check-anchors \ --check-images \ --verbose \ --list $HOME/files.json`	This step uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes all the parameters it needs to run.
YAML `- name: Link check (critical, all files) run: \| ./script/rendered-content-link-checker.mjs \ --language en \ --exit \ --verbose \ --check-images \ --level critical`	This step also uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes a different set of parameters.

次のステップ

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