示例概述
本文档使用一个示例工作流程来演示 GitHub Actions 的一些主要 CI 功能。当此工作流程被触发时,它会自动运行一个脚本,该脚本检查 GitHub Docs 网站是否存在任何失效链接。
下图显示了工作流程步骤的高级视图以及它们如何在作业中运行
本示例中使用的功能
示例工作流程演示了 GitHub Actions 的以下功能。
功能 | 实现 |
---|---|
自动触发工作流程运行 | 推送 |
自动触发工作流程运行 | 拉取请求 |
从 UI 手动运行工作流 | workflow_dispatch |
设置令牌的权限 | 权限 |
控制同时运行的工作流运行或作业数量 | 并发 |
根据仓库在不同的运行器上运行作业 | runs-on |
将您的仓库克隆到运行器 | actions/checkout |
在运行器上安装 node | actions/setup-node |
使用第三方操作 | trilom/file-changes-action |
在运行器上运行脚本 | 使用 ./script/rendered-content-link-checker.mjs |
示例工作流
以下工作流由 GitHub 文档工程团队创建。要查看此文件在 github/docs
仓库中的最新版本,请参阅 check-broken-links-github-github.yml
。
以下工作流会渲染文档中每个页面的内容,并检查所有内部链接以确保它们连接正确。
# This defines the name of the workflow as it will appear in the "Actions" tab of the GitHub repository. 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:
on
键允许您定义运行工作流时触发的事件。您可以在此处定义多个事件。有关更多信息,请参阅“触发工作流”。
workflow_dispatch:
如果您希望能够从 UI 手动运行此工作流,请添加 workflow_dispatch
事件。有关更多信息,请参阅 workflow_dispatch
。
push:
branches:
- main
添加 push
事件,以便每次将提交推送到名为 main
的分支时,工作流都会自动运行。有关更多信息,请参阅 push
。
pull_request:
添加 pull_request
事件,以便每次创建或更新拉取请求时自动运行工作流。有关更多信息,请参阅 pull_request
。
permissions:
contents: read
pull-requests: read
这将修改授予 GITHUB_TOKEN
的默认权限。这将根据工作流的需求而有所不同。有关更多信息,请参阅 "为作业分配权限。"。
在本示例中,pull-requests: read
权限是 trilom/file-changes-action
操作所需的,该操作将在本工作流中稍后使用。
concurrency:
group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
cancel-in-progress: true
concurrency
键确保在同一并发组中,一次只运行一个工作流。有关更多信息,请参阅 "使用并发。" concurrency.group
从工作流名称和拉取请求信息生成并发组名称。||
运算符用于定义回退值。concurrency.cancel-in-progress
取消同一并发组中当前正在运行的任何作业或工作流。
jobs:
jobs
键将工作流文件中运行的所有作业分组在一起。
check-links:
此行定义了一个名为 check-links
的作业,该作业存储在 jobs
键中。
runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
本示例中的 runs-on
键配置作业在 GitHub 托管的运行器或自托管的运行器上运行,具体取决于运行工作流的存储库。
在本示例中,如果存储库名为 docs-internal
并且位于 github
组织中,则作业将在自托管的运行器上运行。如果存储库与该路径不匹配,则它将在 GitHub 托管的 ubuntu-latest
运行器上运行。有关这些选项的更多信息,请参阅 "选择作业的运行器。"。
steps:
steps
键将作为 check-links
作业的一部分运行的所有步骤分组在一起。工作流中的每个作业都有自己的 steps
部分。
- name: Checkout
uses: actions/checkout@v4
uses
键告诉作业检索名为 actions/checkout
的操作。这是一个操作,它会签出您的存储库并将其下载到运行器,使您能够对代码运行操作(例如测试工具)。只要您的工作流使用存储库的代码或您使用存储库中定义的操作,您就必须使用签出操作。
- name: Setup node
uses: actions/setup-node@v4
with:
node-version: 16.13.x
cache: npm
此步骤使用 actions/setup-node
操作在运行器上安装指定版本的 Node.js 软件包,这使您可以访问 npm
命令。
- name: Install
run: npm ci
run
键告诉作业在运行器上执行命令。在本例中,npm ci
用于安装项目的 npm 软件包。
- name: Gather files changed
uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
with:
fileOutput: 'json'
此步骤使用 trilom/file-changes-action
操作来收集所有已更改的文件。此示例固定到操作的特定版本,使用 a6ca26c14274c33b15e6499323aac178af06ad4b
SHA。
在本例中,此步骤创建文件 "${{ env.HOME }}/files.json",以及其他文件。
- name: Show files changed
run: cat $HOME/files.json
为了帮助验证,此步骤列出了 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
此步骤使用 run
命令执行存储在存储库中 script/rendered-content-link-checker.mjs
的脚本,并传递其运行所需的所有参数。
- 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
的脚本,并传递一组不同的参数。
# This defines the name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
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 的基础知识,您可以在 "关于工作流" 中了解工作流及其功能。