Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.
All products
GitHub 操作

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

In this article

如何使用基本 GitHub Actions 功能进行持续集成 (CI)。

示例概述

本文使用示例工作流演示 GitHub Actions 的某些主要 CI 功能。 此工作流触发后，会自动运行一个脚本，检查 GitHub Docs 站点是否有任何损坏的链接。

下图显示了工作流步骤的高级视图以及它们如何在作业中运行：

工作流步骤概述图

此示例中使用的功能

示例工作流演示了 GitHub Actions 的以下功能：

功能实现
触发工作流以自动运行：push

示例工作流

GitHub Docs 工程团队创建了以下工作流。 若要查看 github/docs 存储库中此文件的最新版本，请参阅 check-broken-links-github-github.yml。

注意：此工作流的每一行将在下一部分“了解示例”中介绍。
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

了解示例

下表介绍了在创建 GitHub Actions 工作流时如何使用这些功能。

代码 解释
YAML
name: 'Link Checker: All English'

将显示在 GitHub 存储库的“操作”选项卡中的工作流名称。
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 中的脚本，并传递一组不同的参数。

后续步骤