使用脚本在运行器上测试代码

示例概述

This article uses an example workflow to demonstrate some of the main CI features of GitHub Actions. 此工作流程被触发时，它会自动运行一个脚本，用于检查 GitHub 文档网站是否有任何断开的链接。

The following diagram shows a high level view of the workflow's steps and how they run within the job:

工作流程步骤概览图

此示例中使用的功能

The example workflow demonstrates the following capabilities of GitHub Actions:

功能	实现

Triggering a workflow to run automatically:	`push`
Triggering a workflow to run automatically:	`pull_request`
Manually running a workflow from the UI:	`workflow_dispatch`
Setting permissions for the token:	`permissions`
Controlling how many workflow runs or jobs can run at the same time:	`concurrency`
在不同的运行器上运行作业，具体取决于存储库：	`runs-on`
Cloning your repository to the runner:	`actions/checkout`
Installing `node` on the runner:	`actions/setup-node`
使用第三方操作：	`trilom/file-changes-action`

示例工作流程

The following workflow was created by the GitHub Docs Engineering team. To review the latest version of this file in the github/docs repository, see link-check-all.yml.

Note: Each line of this workflow is explained in the next section at "Understanding the example."

YAML

name: 'Link Checker: All English'

# **What it does**: Renders the content of every page and check all internal links.
# **Why we have it**: To make sure all links connect correctly.
# **Who does it impact**: Docs content.

on:
  workflow_dispatch:
  push:
    branches:
      - main
  pull_request:

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:
  check-links:
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
    steps:
      - name: Checkout
        uses: actions/checkout@v3

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

      - name: Install
        run: npm ci

      # Creates file "$/files.json", among others
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

      # For verification
      - name: Show files changed
        run: cat $HOME/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

      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

了解示例

The following table explains how each of these features are used when creating a GitHub Actions workflow.

代码	说明
YAML `name: 'Link Checker: All English'`	The name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
YAML `on:`	“on”关键字允许您定义在工作流程运行时触发的事件。您可以在此处定义多个事件。更多信息请参阅“触发工作流程”。
YAML `workflow_dispatch:`	如果您希望能够从 UI 手动运行此工作流程，请添加“workflow_dispatch”事件。更多信息请参阅 `workflow_dispatch`。
YAML `push: branches: - main`	添加 'push' 事件，以便每次将提交推送到分支 `main` 时，工作流程都会自动运行。更多信息请参阅 `push`。
YAML `pull_request:`	添加“pull_request”事件，以便每次创建或更新拉取请求时工作流程自动运行。更多信息请参阅 `pull_request`。
YAML `permissions: contents: read pull-requests: read`	修改授予“GITHUB_TOKEN”的默认权限。这将因工作流程的需求而异。更多信息请参阅“为作业分配权限”。
YAML `concurrency: group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label \|\| github.head_ref \|\| github.ref }}'`	为特定事件创建并发组，并使用“\|\|' 运算符来定义回退值。更多信息请参阅“使用并发”。
YAML `cancel-in-progress: true`	取消同一并发组中任何当前正在运行的作业或工作流程。
YAML `jobs:`	将工作流程文件中运行的所有作业组合在一起。
YAML `check-links:`	定义 ID 为“check-links”的作业，该作业存储在“jobs”键中。
YAML `runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}`	将作业配置为在 GitHub 托管的运行器或自托管运行器上运行，具体取决于运行工作流程的存储库。在此示例中，如果存储库名为“docs-internal”并且位于“github”组织内，则作业将在自托管运行器上运行。如果存储库与此路径不匹配，则它将在 GitHub 托管的“ubuntu-latest”运行器上运行。有关这些选项的更多信息，请参阅“为作业选择运行器”。
YAML `steps:`	组合将作为“check-links”作业一部分运行的所有步骤。工作流程中的每个作业都有自己的“steps”部分。
YAML `- name: Checkout uses: actions/checkout@v3`	“uses”关键字告诉作业检索名为“actions/checkout”的操作。这是检出仓库并将其下载到运行器的操作，允许针对您的代码运行操作（例如测试工具）。只要工作流程针对仓库的代码运行，或者您使用仓库中定义的操作，您都必须使用检出操作。
YAML `- name: Setup node uses: actions/setup-node@v3 with: node-version: 16.13.x cache: npm`	此步骤使用“actions/setup-node”操作在运行器上安装指定版本的 Node.js 软件包，这使您可以访问“npm”命令。
YAML `- name: Install run: npm ci`	“run”关键字指示作业在运行器上执行命令。在这种情况下，“npm ci”用于为项目安装 npm 软件包。
YAML `- name: Gather files changed uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b with: fileOutput: 'json'`	使用“trilom/file-changes-action”操作来收集所有已更改的文件。此示例使用 'a6ca26c14274c33b15e6499323aac178af06ad4b' SHA固定到操作的特定版本。
YAML `- name: Show files changed run: cat $HOME/files.json`	列出“files.json”的内容。这将在工作流程运行的日志中可见，并且对于调试非常有用。
YAML `- 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”中的脚本，并传递运行所需的所有参数。
YAML `- 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”中的脚本，并传递一组不同的参数。

后续步骤

To learn about GitHub Actions concepts, see "Understanding GitHub Actions."
For more step-by-step guide for creating a basic workflow, see "Quickstart for GitHub Actions."
If you're comfortable with the basics of GitHub Actions, you can learn about workflows and their features at "About workflows."