サンプルの概要
この記事では、ワークフローの例を使って、GitHub Actions の主な CI 機能の一部を示します。このワークフローがトリガーされると、npm test
とテストの組み合わせのマトリックスを使ってコードがテストされます。
次の図は、ワークフローの手順とジョブ内でそれを実行する方法の概要を示したものです。
この例で使用されている機能
このワークフロー例は、GitHub Actions の次の機能を示しています。
機能 | 実装 |
---|---|
UI からワークフローを手動で実行する: | workflow_dispatch |
ワークフローの例
次のワークフローは、GitHub ドキュメント エンジニアリング チームによって作成されました。 github/docs
リポジトリ内でこのファイルの最新バージョンを確認するには、次を参照してください。 test.yml
。
注: このワークフローの各行については、次のセクションの「例の説明」に説明があります。
name: Node.js Tests
# **What it does**: Runs our tests.
# **Why we have it**: We want our tests to pass before merging code.
# **Who does it impact**: Docs engineering, open-source engineering contributors.
on:
workflow_dispatch:
pull_request:
push:
branches:
- main
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:
test:
# Run on self-hosted if the private repo or ubuntu-latest if the public repo
# See pull # 17442 in the private repo for context
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
timeout-minutes: 60
strategy:
fail-fast: false
matrix:
# The same array lives in test-windows.yml, so make any updates there too.
test-group:
[
content,
graphql,
meta,
rendering,
routing,
unit,
linting,
translations,
]
steps:
# Each of these ifs needs to be repeated at each step to make sure the required check still runs
# Even if if doesn't do anything
- name: Check out repo
uses: actions/checkout@v3
with:
# Not all test suites need the LFS files. So instead, we opt to
# NOT clone them initially and instead, include them manually
# only for the test groups that we know need the files.
lfs: ${{ matrix.test-group == 'content' }}
# Enables cloning the Early Access repo later with the relevant personal access token
persist-credentials: 'false'
- name: Figure out which docs-early-access branch to checkout, if internal repo
if: ${{ github.repository == 'github/docs-internal' }}
id: check-early-access
uses: actions/github-script@v6
env:
BRANCH_NAME: ${{ github.head_ref || github.ref_name }}
with:
github-token: ${{ secrets.DOCUBOT_REPO_PAT }}
result-encoding: string
script: |
// If being run from a PR, this becomes 'my-cool-branch'.
// If run on main, with the `workflow_dispatch` action for
// example, the value becomes 'main'.
const { BRANCH_NAME } = process.env
try {
const response = await github.repos.getBranch({
owner: 'github',
repo: 'docs-early-access',
BRANCH_NAME,
})
console.log(`Using docs-early-access branch called '${BRANCH_NAME}'.`)
return BRANCH_NAME
} catch (err) {
if (err.status === 404) {
console.log(`There is no docs-early-access branch called '${BRANCH_NAME}' so checking out 'main' instead.`)
return 'main'
}
throw err
}
- name: Check out docs-early-access too, if internal repo
if: ${{ github.repository == 'github/docs-internal' }}
uses: actions/checkout@v3
with:
repository: github/docs-early-access
token: ${{ secrets.DOCUBOT_REPO_PAT }}
path: docs-early-access
ref: ${{ steps.check-early-access.outputs.result }}
- name: Merge docs-early-access repo's folders
if: ${{ github.repository == 'github/docs-internal' }}
run: |
mv docs-early-access/assets assets/images/early-access
mv docs-early-access/content content/early-access
mv docs-early-access/data data/early-access
rm -r docs-early-access
# This is necessary when LFS files where cloned but does nothing
# if actions/checkout was run with `lfs:false`.
- name: Checkout LFS objects
run: git lfs checkout
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
id: get_diff_files
with:
# So that `steps.get_diff_files.outputs.files` becomes
# a string like `foo.js path/bar.md`
output: ' '
- name: Insight into changed files
run: |
# Must to do this because the list of files can be HUGE. Especially
# in a repo-sync when there are lots of translation files involved.
echo "${{ steps.get_diff_files.outputs.files }}" > get_diff_files.txt
- name: Setup node
uses: actions/setup-node@v3
with:
node-version: 16.14.x
cache: npm
- name: Install dependencies
run: npm ci
- name: Cache nextjs build
uses: actions/cache@v3
with:
path: .next/cache
key: ${{ runner.os }}-nextjs-${{ hashFiles('package*.json') }}
- name: Run build script
run: npm run build
- name: Run tests
env:
DIFF_FILE: get_diff_files.txt
CHANGELOG_CACHE_FILE_PATH: tests/fixtures/changelog-feed.json
run: npm test -- tests/${{ matrix.test-group }}/
例の説明
次の表では、GitHub Actions ワークフローを作成するときにこれらの各機能がどのように使われるかを説明します。
"コード" | 説明 |
---|---|
|
GitHub リポジトリの [アクション] タブに表示されるワークフローの名前。 |
|
|
|
UI でこのワークフローを手動で実行できるようにする場合は、 |
|
pull request が作成または更新されるたびにワークフローが自動的に実行されるようにするには、 |
|
フィルター |
|
|
|
特定のイベントに対するコンカレンシー グループを作成し、 |
|
同じコンカレンシー グループ内の現在実行中のジョブまたはワークフローを取り消します。 |
|
ワークフロー ファイルで実行されるすべてのジョブをグループ化します。 |
|
|
|
ワークフローを実行するリポジトリに応じて、GitHub ホステッド ランナーまたはセルフホステッド ランナー上で実行するようにジョブを構成します。 この例では、リポジトリ名が |
|
実行したジョブが自動的に取り消されるまでの最大分数を設定します。 詳細については、「 |
|
このセクションで、ジョブのビルド マトリックスを定義します。 |
|
|
|
テスト グループの配列を含む |
|
|
|
|
|
現在のリポジトリが |
|
現在のリポジトリが |
|
現在のリポジトリが |
|
この手順では、リポジトリから LFS オブジェクトをチェックアウトするコマンドを実行します。 |
|
この手順では、 |
|
この手順では、前の手順の出力を使って、pull request で変更されたファイルの一覧を含むファイルを作成するシェル コマンドを実行します。 |
|
この手順では、 |
|
この手順では、 |
|
このステップでは、ワークフローで毎回ゼロからリビルドするのではなく、ビルドのキャッシュを取得するように、 |
|
この手順では、ビルド スクリプトを実行します。 |
|
この手順では、 |
次の手順
- GitHub Actions の概念について確認するには、「GitHub Actions を理解する」を参照してください。
- 基本的なワークフローを作成するための詳細な手順については、「GitHub Actions のクイックスタート」を参照してください。
- GitHub Actions の基本操作に慣れている場合、ワークフローとその機能については「ワークフローについて」で確認できます。