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

示例概述

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

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

工作流步骤概述图

此示例中使用的功能

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

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

示例工作流

GitHub Docs 工程团队创建了以下工作流。若要查看 github/docs 存储库中此文件的最新版本，请参阅 link-check-all.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` 中的脚本，并传递一组不同的参数。

后续步骤

若要了解 GitHub Actions 概念，请参阅“了解 GitHub Actions”。
有关创建基本工作流的分步指南，请参阅“GitHub Actions 快速入门”。
如果你熟悉 GitHub Actions 的基础知识，可以在“关于工作流”中了解工作流及其功能。