注: GitHub ホステッド ランナーは、現在 GitHub Enterprise Server でサポートされていません。 GitHub public roadmap で、今後の計画的なサポートの詳細を確認できます。
サンプルの概要
この記事では、ワークフローの例を使って、GitHub Actions の主な CI 機能の一部を示します。 このワークフローがトリガーされると、GitHub Docs サイトに壊れたリンクがあるかどうかを確認するスクリプトが自動的に実行されます。
次の図は、ワークフローの手順とジョブ内でそれを実行する方法の概要を示したものです。

この例で使用されている機能
このワークフロー例は、GitHub Actions の次の機能を示しています。
| 機能 | 実装 |
|---|---|
| ワークフローをトリガーして自動的に実行する | push |
| ワークフローをトリガーして自動的に実行する | pull_request |
| UI からワークフローを手動で実行する | workflow_dispatch |
| トークンのアクセス許可の設定 | permissions |
| 同時に実行できるワークフロー実行またはジョブの数を制御する | concurrency |
| リポジトリに応じたさまざまなランナー上のジョブの実行 | runs-on |
ランナーへの node のインストール | actions/setup-node |
| サード パーティのアクションの使用 | trilom/file-changes-action |
ワークフローの例
次のワークフローは、GitHub ドキュメント エンジニアリング チームによって作成されました。 github/docs リポジトリ内でこのファイルの最新バージョンを確認するには、次を参照してください。 check-broken-links-github-github.yml。
次のワークフローでは、ドキュメント内のすべてのページの内容をレンダリングし、すべての内部リンクが正しく接続されていることを確認します。
# これにより、GitHub リポジトリの [アクション] タブに表示されるワークフローの名前が定義されます。
name: 'Link Checker: All English'
# The `on` key 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 from the UI. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
workflow_dispatch:
# Add the `push` event, 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
# 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:
# 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)."
#
# In this example, the `pull-requests: read` permission is needed for the `trilom/file-changes-action` action that is used later in this workflow.
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
# The `jobs` key groups together all the jobs that run in the workflow file.
jobs:
# This line defines a job with the ID `check-links` that is stored within the `jobs` key.
check-links:
# The `runs-on` key in this example 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'] }}
# The `steps` key groups together all the steps that will run as part of the `check-links` job. Each job in a workflow has its own `steps` section.
steps:
# The `uses` key 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 the repository's code or you are using an action defined in the repository.
- name: Checkout
uses: actions/checkout@v4
# This step uses the `actions/setup-node` action to install the specified version of the Node.js 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.13.x
cache: npm
# The `run` key tells the job to execute a command on the runner. In this example, `npm ci` is used to install the npm software packages for the project.
- name: Install
run: npm ci
# This step uses the `trilom/file-changes-action` action to gather all the changed files. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
#
# In this example, this step creates the file "${{ env.HOME }}/files.json", among others.
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'
# To help with verification, this step lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging.
- name: Show files changed
run: cat $HOME/files.json
# This step uses the `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes all the parameters it needs to run.
- 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
# This step also uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes a different set of parameters.
- name: Link check (critical, all files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--exit \
--verbose \
--check-images \
--level critical
name: 'Link Checker: All English'これにより、GitHub リポジトリの [アクション] タブに表示されるワークフローの名前が定義されます。
on:The on key 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 from the UI. For more information, see workflow_dispatch.
push:
branches:
- mainAdd the push event, so that the workflow runs automatically every time a commit is pushed to a branch called main. For more information, see push.
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.
permissions:
contents: read
pull-requests: readThis modifies the default permissions granted to GITHUB_TOKEN. This will vary depending on the needs of your workflow. For more information, see "権限をジョブに割り当てる."
In this example, the pull-requests: read permission is needed for the trilom/file-changes-action action that is used later in this workflow.
concurrency:
group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
cancel-in-progress: trueThe 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:The jobs key groups together all the jobs that run in the workflow file.
check-links:This line defines a job with the ID check-links that is stored within the jobs key.
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}The runs-on key in this example 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 "ジョブのランナーを選択する."
steps:The steps key groups together all the steps that will run as part of the check-links job. Each job in a workflow has its own steps section.
- name: Checkout
uses: actions/checkout@v4The uses key 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 the repository's code or you are using an action defined in the repository.
- name: Setup node
uses: actions/setup-node@v4
with:
node-version: 16.13.x
cache: npmThis step uses the actions/setup-node action to install the specified version of the Node.js software package on the runner, which gives you access to the npm command.
- name: Install
run: npm ciThe run key tells the job to execute a command on the runner. In this example, npm ci is used to install the npm software packages for the project.
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'This step uses the trilom/file-changes-action action to gather all the changed files. This example is pinned to a specific version of the action, using the a6ca26c14274c33b15e6499323aac178af06ad4b SHA.
In this example, this step creates the file "${{ env.HOME }}/files.json", among others.
- name: Show files changed
run: cat $HOME/files.jsonTo help with verification, this step lists the contents of files.json. This will be visible in the workflow run's log, and can be useful for debugging.
- 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.jsonThis step uses the run command to execute a script that is stored in the repository at script/rendered-content-link-checker.mjs and passes all the parameters it needs to run.
- name: Link check (critical, all files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--exit \
--verbose \
--check-images \
--level criticalThis step also uses run command to execute a script that is stored in the repository at script/rendered-content-link-checker.mjs and passes a different set of parameters.
# これにより、GitHub リポジトリの [アクション] タブに表示されるワークフローの名前が定義されます。
name: 'Link Checker: All English'
# The `on` key 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 from the UI. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
workflow_dispatch:
# Add the `push` event, 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
# 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:
# 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)."
#
# In this example, the `pull-requests: read` permission is needed for the `trilom/file-changes-action` action that is used later in this workflow.
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
# The `jobs` key groups together all the jobs that run in the workflow file.
jobs:
# This line defines a job with the ID `check-links` that is stored within the `jobs` key.
check-links:
# The `runs-on` key in this example 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'] }}
# The `steps` key groups together all the steps that will run as part of the `check-links` job. Each job in a workflow has its own `steps` section.
steps:
# The `uses` key 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 the repository's code or you are using an action defined in the repository.
- name: Checkout
uses: actions/checkout@v4
# This step uses the `actions/setup-node` action to install the specified version of the Node.js 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.13.x
cache: npm
# The `run` key tells the job to execute a command on the runner. In this example, `npm ci` is used to install the npm software packages for the project.
- name: Install
run: npm ci
# This step uses the `trilom/file-changes-action` action to gather all the changed files. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
#
# In this example, this step creates the file "${{ env.HOME }}/files.json", among others.
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'
# To help with verification, this step lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging.
- name: Show files changed
run: cat $HOME/files.json
# This step uses the `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes all the parameters it needs to run.
- 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
# This step also uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes a different set of parameters.
- name: Link check (critical, all files)
run: |
./script/rendered-content-link-checker.mjs \
--language en \
--exit \
--verbose \
--check-images \
--level critical
次の手順
- GitHub Actions の概念について確認するには、「GitHub Actions を理解する」を参照してください。
- 基本的なワークフローを作成するための詳細な手順については、「GitHub Actions のクイックスタート」を参照してください。
- GitHub Actions の基本操作に慣れている場合、ワークフローとその機能については「ワークフローについて」で確認できます。