Skip to main content

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

継続的インテグレーション (CI) のために基本的な GitHub Actions 機能を使用する方法。

サンプルの概要

この記事では、ワークフローの例を使って、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 のリポジトリに格納されているスクリプトを実行し、さまざまなパラメーターのセットを渡します。

次の手順