Skip to main content

Using scripts to test your code on a runner

How to use essential GitHub Actions features for continuous integration (CI).

ノート: 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.

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

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@v2

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

次のステップ