示例概述
本文使用示例工作流演示 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 Docs 工程团队创建了以下工作流。 若要查看 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@v3 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:
- main
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
.
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: read
This 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: 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:
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@v4
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: Setup node
uses: actions/setup-node@v3
with:
node-version: 16.13.x
cache: npm
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: Install
run: npm ci
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: 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.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: 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 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 critical
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.
# 这定义工作流的名称,它将显示在 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@v3
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 的基础知识,可以在“关于工作流程”中了解工作流及其功能。