Skip to main content

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

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

示例概述

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”中的脚本,并传递一组不同的参数。

后续步骤