Skip to main content

コンカレンシー、式、テスト マトリックスの使用

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

サンプルの概要

この記事では、ワークフローの例を使って、GitHub Actions の主な CI 機能の一部を示します。このワークフローがトリガーされると、npm test とテストの組み合わせのマトリックスを使ってコードがテストされます。

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

テスト マトリックスを使うワークフローをトリガーするイベントの図。

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

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

機能実装
UI からワークフローを手動で実行するworkflow_dispatch
ワークフローをトリガーして自動的に実行するpull_request
定期的なワークフローの実行schedule
トークンのアクセス許可の設定permissions
同時に実行できるワークフロー実行またはジョブの数を制御するconcurrency
リポジトリに応じたさまざまなランナー上のジョブの実行runs-on
さまざまなテスト構成を作成するマトリックスの使用matrix
ランナーへの node のインストールactions/setup-node
依存関係のキャッシュactions/cache
ランナー上のテストの実行npm test

ワークフローの例

次のワークフローは、GitHub ドキュメント エンジニアリング チームによって作成されました。 このワークフローは、pull request 内のコードに対してテストを実行します。 github/docs リポジトリ内でこのファイルの最新バージョンを確認するには、test.yml を参照してください。

YAML
name: Node.js Tests

これにより、GitHub リポジトリの [アクション] タブに表示されるワークフローの名前が定義されます。

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 "ワークフローのトリガー."

  workflow_dispatch:

Add the workflow_dispatch event if you want to be able to manually run this workflow. For more information, see workflow_dispatch.

  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.

  push:
    branches:
      - main

Add the push event with the branch filter, so that the workflow runs automatically every time a commit is pushed to a branch called "main". For more information, see push.

permissions:
  contents: read
  pull-requests: read

This modifies the default permissions granted to GITHUB_TOKEN. This will vary depending on the needs of your workflow. For more information, see "権限をジョブに割り当てる."

concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

The concurrency key ensures that only a single workflow in the same concurrency group will run at the same time. For more information, see "コンカレンシーの使用." concurrency.group generates a concurrency group name from the workflow name and pull request information. The || operator is used to define fallback values. concurrency.cancel-in-progress cancels any currently running job or workflow in the same concurrency group.

jobs:

This groups together all the jobs that run in the workflow file.

  test:

This defines a job with the ID test that is stored within the jobs key.

    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}

This 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 "ジョブのランナーを選択する."

    timeout-minutes: 60

This sets the maximum number of minutes to let the job run before it is automatically canceled. For more information, see timeout-minutes.

    strategy:

This section defines the build matrix for your jobs.

      fail-fast: false

Setting fail-fast to false prevents GitHub from cancelling all in-progress jobs if any matrix job fails.

      matrix:
        test-group:
          [
            content,
            graphql,
            meta,
            rendering,
            routing,
            unit,
            linting,
            translations,
          ]

This creates a matrix named test-group, with an array of test groups. These values match the names of test groups that will be run by npm test.

    steps:

This groups together all the steps that will run as part of the test job. Each job in a workflow has its own steps section.

      - name: Check out repo
        uses: actions/checkout@v4
        with:
          lfs: ${{ matrix.test-group == 'content' }}
          persist-credentials: 'false'

The uses keyword tells the job to retrieve the action named actions/checkout. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will use your repository's code. Some extra options are provided to the action using the with key.

      - name: Checkout LFS objects
        run: git lfs checkout

This step runs a command to check out large file storage (LFS) objects from the repository.

      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        id: get_diff_files
        with:
          output: ' '

This step uses the trilom/file-changes-action action to gather the files changed in the pull request, so they can be analyzed in the next step. This example is pinned to a specific version of the action, using the a6ca26c14274c33b15e6499323aac178af06ad4b SHA.

      - name: Insight into changed files
        run: |
          echo "${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt

This step runs a shell command that uses an output from the previous step to create a file containing the list of files changed in the pull request.

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

This step uses the actions/setup-node action to install the specified version of the node software package on the runner, which gives you access to the npm command.

      - name: Install dependencies
        run: npm ci

This step runs the npm ci shell command to install the npm software packages for the project.

      - name: Cache nextjs build
        uses: actions/cache@v3
        with:
          path: .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('package*.json') }}

This step uses the actions/cache action to cache the Next.js build, so that the workflow will attempt to retrieve a cache of the build, and not rebuild it from scratch every time. For more information, see "依存関係をキャッシュしてワークフローのスピードを上げる."

      - name: Run build script
        run: npm run build

This step runs the build script.

      - name: Run tests
        env:
          DIFF_FILE: get_diff_files.txt
          CHANGELOG_CACHE_FILE_PATH: src/fixtures/fixtures/changelog-feed.json
        run: npm test -- tests/${{ matrix.test-group }}/

This step runs the tests using npm test, and the test matrix provides a different value for ${{ matrix.test-group }} for each job in the matrix. It uses the DIFF_FILE environment variable to know which files have changed, and uses the CHANGELOG_CACHE_FILE_PATH environment variable for the changelog cache file.

# これにより、GitHub リポジトリの [アクション] タブに表示されるワークフローの名前が定義されます。
name: Node.js Tests

# 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 "[AUTOTITLE](/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows)."
on:

  # Add the `workflow_dispatch` event if you want to be able to manually run this workflow. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
  workflow_dispatch:

  # 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`](/actions/using-workflows/events-that-trigger-workflows#pull_request).
  pull_request:

  # Add the `push` event with the `branch` filter, so that the workflow runs automatically every time a commit is pushed to a branch called "main". For more information, see [`push`](/actions/using-workflows/events-that-trigger-workflows#push).
  push:
    branches:
      - main

# This modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "[AUTOTITLE](/actions/using-jobs/assigning-permissions-to-jobs)."
permissions:
  contents: read
  pull-requests: read

# The `concurrency` key ensures that only a single workflow in the same concurrency group will run at the same time. For more information, see "[AUTOTITLE](/actions/using-jobs/using-concurrency)."
# `concurrency.group` generates a concurrency group name from the workflow name and pull request information. The `||` operator is used to define fallback values.
# `concurrency.cancel-in-progress` cancels any currently running job or workflow in the same concurrency group.
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

# This groups together all the jobs that run in the workflow file.
jobs:

  # This defines a job with the ID `test` that is stored within the `jobs` key.
  test:

    # This 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 "[AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job)."
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}

    # This sets the maximum number of minutes to let the job run before it is automatically canceled. For more information, see [`timeout-minutes`](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes).
    timeout-minutes: 60

    # This section defines the build matrix for your jobs.
    strategy:

      # Setting `fail-fast` to `false` prevents GitHub from cancelling all in-progress jobs if any matrix job fails.
      fail-fast: false

      # This creates a matrix named `test-group`, with an array of test groups. These values match the names of test groups that will be run by `npm test`.
      matrix:
        test-group:
          [
            content,
            graphql,
            meta,
            rendering,
            routing,
            unit,
            linting,
            translations,
          ]

    # This groups together all the steps that will run as part of the `test` job. Each job in a workflow has its own `steps` section.
    steps:

      # The `uses` keyword tells the job to retrieve the action named `actions/checkout`. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will use your repository's code. Some extra options are provided to the action using the `with` key.
      - name: Check out repo
        uses: actions/checkout@v4
        with:
          lfs: ${{ matrix.test-group == 'content' }}
          persist-credentials: 'false'

      # This step runs a command to check out large file storage (LFS) objects from the repository.
      - name: Checkout LFS objects
        run: git lfs checkout

      # This step uses the `trilom/file-changes-action` action to gather the files changed in the pull request, so they can be analyzed in the next step. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        id: get_diff_files
        with:
          output: ' '

      # This step runs a shell command that uses an output from the previous step to create a file containing the list of files changed in the pull request.
      - name: Insight into changed files
        run: |

          echo "${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt

      # This step uses the `actions/setup-node` action to install the specified version of the `node` software package on the runner, which gives you access to the `npm` command.
      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version: 16.14.x
          cache: npm

      # This step runs the `npm ci` shell command to install the npm software packages for the project.
      - name: Install dependencies
        run: npm ci

      # This step uses the `actions/cache` action to cache the Next.js build, so that the workflow will attempt to retrieve a cache of the build, and not rebuild it from scratch every time. For more information, see "[AUTOTITLE](/actions/using-workflows/caching-dependencies-to-speed-up-workflows)."
      - name: Cache nextjs build
        uses: actions/cache@v3
        with:
          path: .next/cache
          key: ${{ runner.os }}-nextjs-${{ hashFiles('package*.json') }}

      # This step runs the build script.
      - name: Run build script
        run: npm run build

      # This step runs the tests using `npm test`, and the test matrix provides a different value for `${{ matrix.test-group }}` for each job in the matrix. It uses the `DIFF_FILE` environment variable to know which files have changed, and uses the `CHANGELOG_CACHE_FILE_PATH` environment variable for the changelog cache file.
      - name: Run tests
        env:
          DIFF_FILE: get_diff_files.txt
          CHANGELOG_CACHE_FILE_PATH: src/fixtures/fixtures/changelog-feed.json
        run: npm test -- tests/${{ matrix.test-group }}/

次の手順