Skip to main content

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

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

示例概述

本文使用示例工作流演示 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 中的脚本,并传递一组不同的参数。

后续步骤