スクリプトを使ってランナーでコードをテストする

サンプルの概要

この記事では、ワークフローの例を使って、GitHub Actions の主な CI 機能の一部を示します。このワークフローがトリガーされると、GitHub Docs サイトに壊れたリンクがあるかどうかを確認するスクリプトが自動的に実行されます。

次の図は、ワークフローの手順とジョブ内でそれを実行する方法の概要を示したものです。

ワークフローのステップの概要図

この例で使用されている機能

このワークフロー例は、GitHub Actions の次の機能を示しています。

機能	実装
ワークフローをトリガーして自動的に実行する	`push`

ワークフローの例

次のワークフローは、GitHub ドキュメントエンジニアリングチームによって作成されました。 github/docs リポジトリ内でこのファイルの最新バージョンを確認するには、次を参照してください。 check-broken-links-github-github.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

例の説明

次の表では、GitHub Actions ワークフローを作成するときにこれらの各機能がどのように使われるかを説明します。

"コード"	説明
YAML `name: 'Link Checker: All English'`	GitHub リポジトリの [アクション] タブに表示されるワークフローの名前。
YAML `on:`	`on` キーワードを使うと、ワークフローの実行時にトリガーするイベントを定義できます。ここでは複数のイベントを定義できます。詳しくは、「ワークフローのトリガー」を参照してください。
YAML `workflow_dispatch:`	このワークフローを UI から手動で実行できるようにする場合は、`workflow_dispatch` イベントを追加します。詳細については、「`workflow_dispatch`」を参照してください。
YAML `push: branches: - main`	`main` というブランチにコミットがプッシュされるたびにワークフローが自動的に実行されるようにするには、`push` イベントを追加します。詳細については、「`push`」を参照してください。
YAML `pull_request:`	pull request が作成または更新されるたびにワークフローが自動的に実行されるようにするには、`pull_request` イベントを追加します。詳細については、「`pull_request`」を参照してください。
YAML `permissions: contents: read pull-requests: read`	`GITHUB_TOKEN` に付与される既定のアクセス許可を変更します。これはワークフローのニーズによって異なります。詳しくは、「権限をジョブに割り当てる」を参照してください。
YAML `concurrency: group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label \|\| github.head_ref \|\| github.ref }}'`	特定のイベントに対するコンカレンシーグループを作成し、`\|\|` 演算子を使ってフォールバック値を定義します。詳しくは、「コンカレンシーの使用」を参照してください。
YAML `cancel-in-progress: true`	同じコンカレンシーグループ内の現在実行中のジョブまたはワークフローを取り消します。
YAML `jobs:`	ワークフローファイルで実行されるすべてのジョブをグループ化します。
YAML `check-links:`	`jobs` キー内に格納されている ID `check-links` を持つジョブを定義します。
YAML `runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}`	ワークフローを実行するリポジトリに応じて、GitHub ホステッドランナーまたはセルフホステッドランナー上で実行するようにジョブを構成します。この例では、リポジトリ名が `docs-internal` であり、`github` 組織内にある場合、ジョブはセルフホステッドランナー上で実行されます。このパスに一致しないリポジトリは、GitHub によってホストされる `ubuntu-latest` ランナー上で実行されます。これらのオプションについて詳しくは、「ジョブのランナーを選択する」を参照してください。
YAML `steps:`	`check-links` ジョブの一部として実行されるすべてのステップをグループ化します。ワークフロー内の各ジョブには、独自の `steps` セクションがあります。
YAML `- name: Checkout uses: actions/checkout@v3`	`uses` キーワードは、`actions/checkout` という名前のアクションを取得するようにジョブに指示します。これは、リポジトリをチェックアウトしてランナーにダウンロードし、コードに対してアクション（テストツールなど）を実行できるようにします。ワークフローがリポジトリのコードに対して実行されるとき、またはリポジトリで定義されたアクションを使用しているときはいつでも、チェックアウトアクションを使用する必要があります。
YAML `- name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm`	このステップでは、`actions/setup-node` アクションを使用して、指定したバージョンの Node.js ソフトウェアパッケージをランナーにインストールします。これにより、`npm` コマンドにアクセスできるようになります。
YAML `- name: Install run: npm ci`	`run` キーワードは、ランナーでコマンドを実行するようにジョブに指示します。この場合、`npm ci` はプロジェクトの npm ソフトウェアパッケージをインストールするために使用されます。
YAML `- name: Gather files changed uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b with: fileOutput: 'json'`	`trilom/file-changes-action` アクションを使用して、変更されたすべてのファイルを収集します。この例は、`a6ca26c14274c33b15e6499323aac178af06ad4b` SHA を使用して、特定のバージョンのアクションに合わせて固定されています。
YAML `- name: Show files changed run: cat $HOME/files.json`	`files.json` の内容を一覧表示します。これはワークフロー実行のログに表示され、デバッグに役立ちます。
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`	このステップでは、`run` コマンドを使って、`script/rendered-content-link-checker.mjs` のリポジトリに格納されているスクリプトを実行し、実行に必要なすべてのパラメーターを渡します。
YAML `- name: Link check (critical, all files) run: \| ./script/rendered-content-link-checker.mjs \ --language en \ --exit \ --verbose \ --check-images \ --level critical`	このステップでも `run` コマンドを使って、`script/rendered-content-link-checker.mjs` のリポジトリに格納されているスクリプトを実行し、さまざまなパラメーターのセットを渡します。

次の手順

GitHub Actions の概念について確認するには、「GitHub Actions を理解する」を参照してください。
基本的なワークフローを作成するための詳細な手順については、「GitHub Actions のクイックスタート」を参照してください。
GitHub Actions の基本操作に慣れている場合、ワークフローとその機能については「ワークフローについて」で確認できます。