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

注: GitHub ホステッドランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。

サンプルの概要

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

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

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

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

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

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

ワークフローの例

次のワークフローは、GitHub ドキュメントエンジニアリングチー� によって作成されました。 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

例の説明

次の表では、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@v2`	`uses` キーワードは、`actions/checkout` という名前のアクションを取得するようにジョブに指示します。これは、リポジトリをチェックアウトしてランナーにダウンロードし、コードに対してアクション（テストツールなど）を実行できるようにします。ワークフローがリポジトリのコードに対して実行されるとき、またはリポジトリで定義されたアクションを使用しているときはいつでも、チェックアウトアクションを使用する必要があります。
YAML `- name: Setup node uses: actions/setup-node@v2 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 の基本操作に慣れている� �合、ワークフローとその機能については「ワークフローについて」で学習できます。