跳至主要内容

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

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

示例概述

本文档使用一个示例工作流程来演示 GitHub Actions 的一些主要 CI 功能。当此工作流程被触发时,它会自动运行一个脚本,该脚本检查 GitHub Docs 网站是否存在任何失效链接。

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

Diagram of an event triggering a workflow that uses scripts to test code.

本示例中使用的功能

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

功能实现
自动触发工作流程运行推送
自动触发工作流程运行拉取请求
从 UI 手动运行工作流workflow_dispatch
设置令牌的权限权限
控制同时运行的工作流运行或作业数量并发
根据仓库在不同的运行器上运行作业runs-on
将您的仓库克隆到运行器actions/checkout
在运行器上安装 nodeactions/setup-node
使用第三方操作trilom/file-changes-action
在运行器上运行脚本使用 ./script/rendered-content-link-checker.mjs

示例工作流

以下工作流由 GitHub 文档工程团队创建。要查看此文件在 github/docs 仓库中的最新版本,请参阅 check-broken-links-github-github.yml

以下工作流会渲染文档中每个页面的内容,并检查所有内部链接以确保它们连接正确。

YAML
name: 'Link Checker: All English'

这定义了工作流的名称,它将显示在 GitHub 仓库的“操作”选项卡中。

on:

on 键允许您定义运行工作流时触发的事件。您可以在此处定义多个事件。有关更多信息,请参阅“触发工作流”。

  workflow_dispatch:

如果您希望能够从 UI 手动运行此工作流,请添加 workflow_dispatch 事件。有关更多信息,请参阅 workflow_dispatch

  push:
    branches:
      - main

添加 push 事件,以便每次将提交推送到名为 main 的分支时,工作流都会自动运行。有关更多信息,请参阅 push

  pull_request:

添加 pull_request 事件,以便每次创建或更新拉取请求时自动运行工作流。有关更多信息,请参阅 pull_request

permissions:
  contents: read
  pull-requests: read

这将修改授予 GITHUB_TOKEN 的默认权限。这将根据工作流的需求而有所不同。有关更多信息,请参阅 "为作业分配权限。"。

在本示例中,pull-requests: read 权限是 trilom/file-changes-action 操作所需的,该操作将在本工作流中稍后使用。

concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

concurrency 键确保在同一并发组中,一次只运行一个工作流。有关更多信息,请参阅 "使用并发。" concurrency.group 从工作流名称和拉取请求信息生成并发组名称。|| 运算符用于定义回退值。concurrency.cancel-in-progress 取消同一并发组中当前正在运行的任何作业或工作流。

jobs:

jobs 键将工作流文件中运行的所有作业分组在一起。

  check-links:

此行定义了一个名为 check-links 的作业,该作业存储在 jobs 键中。

    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}

本示例中的 runs-on 键配置作业在 GitHub 托管的运行器或自托管的运行器上运行,具体取决于运行工作流的存储库。

在本示例中,如果存储库名为 docs-internal 并且位于 github 组织中,则作业将在自托管的运行器上运行。如果存储库与该路径不匹配,则它将在 GitHub 托管的 ubuntu-latest 运行器上运行。有关这些选项的更多信息,请参阅 "选择作业的运行器。"。

    steps:

steps 键将作为 check-links 作业的一部分运行的所有步骤分组在一起。工作流中的每个作业都有自己的 steps 部分。

      - name: Checkout
        uses: actions/checkout@v4

uses 键告诉作业检索名为 actions/checkout 的操作。这是一个操作,它会签出您的存储库并将其下载到运行器,使您能够对代码运行操作(例如测试工具)。只要您的工作流使用存储库的代码或您使用存储库中定义的操作,您就必须使用签出操作。

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

此步骤使用 actions/setup-node 操作在运行器上安装指定版本的 Node.js 软件包,这使您可以访问 npm 命令。

      - name: Install
        run: npm ci

run 键告诉作业在运行器上执行命令。在本例中,npm ci 用于安装项目的 npm 软件包。

      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

此步骤使用 trilom/file-changes-action 操作来收集所有已更改的文件。此示例固定到操作的特定版本,使用 a6ca26c14274c33b15e6499323aac178af06ad4b SHA。

在本例中,此步骤创建文件 "${{ env.HOME }}/files.json",以及其他文件。

      - name: Show files changed
        run: cat $HOME/files.json

为了帮助验证,此步骤列出了 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

此步骤使用 run 命令执行存储在存储库中 script/rendered-content-link-checker.mjs 的脚本,并传递其运行所需的所有参数。

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

# This defines the name of the workflow as it will appear in the "Actions" tab of the GitHub repository.
name: 'Link Checker: All English'

# The `on` key lets you define the events that trigger when the workflow is run. You can define multiple events here. For more information, see "[AUTOTITLE](/actions/using-workflows/triggering-a-workflow#using-events-to-trigger-workflows)."
on:
# Add the `workflow_dispatch` event if you want to be able to manually run this workflow from the UI. For more information, see [`workflow_dispatch`](/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch).
  workflow_dispatch:
  # Add the `push` event, so that the workflow runs automatically every time a commit is pushed to a branch called `main`. For more information, see [`push`](/actions/using-workflows/events-that-trigger-workflows#push).
  push:
    branches:
      - main
  # Add the `pull_request` event, so that the workflow runs automatically every time a pull request is created or updated. For more information, see [`pull_request`](/actions/using-workflows/events-that-trigger-workflows#pull_request).
  pull_request:

# This modifies the default permissions granted to `GITHUB_TOKEN`. This will vary depending on the needs of your workflow. For more information, see "[AUTOTITLE](/actions/using-jobs/assigning-permissions-to-jobs)."
#
# In this example, the `pull-requests: read` permission is needed for the `trilom/file-changes-action` action that is used later in this workflow.
permissions:
  contents: read
  pull-requests: read
# The `concurrency` key ensures that only a single workflow in the same concurrency group will run at the same time. For more information, see "[AUTOTITLE](/actions/using-jobs/using-concurrency)."
# `concurrency.group` generates a concurrency group name from the workflow name and pull request information. The `||` operator is used to define fallback values. 
# `concurrency.cancel-in-progress` cancels any currently running job or workflow in the same concurrency group.
concurrency:
  group: '${{ github.workflow }} @ ${{ github.event.pull_request.head.label || github.head_ref || github.ref }}'
  cancel-in-progress: true

# The `jobs` key groups together all the jobs that run in the workflow file.
jobs:
  # This line defines a job with the ID `check-links` that is stored within the `jobs` key.
  check-links:
    # The `runs-on` key in this example configures the job to run on a GitHub-hosted runner or a self-hosted runner, depending on the repository running the workflow. 
    # 
    # In this example, the job will run on a self-hosted runner if the repository is named `docs-internal` and is within the `github` organization. If the repository doesn't match this path, then it will run on an `ubuntu-latest` runner hosted by GitHub. For more information on these options, see "[AUTOTITLE](/actions/using-jobs/choosing-the-runner-for-a-job)."
    runs-on: ${{ fromJSON('["ubuntu-latest", "self-hosted"]')[github.repository == 'github/docs-internal'] }}
    # The `steps` key groups together all the steps that will run as part of the `check-links` job. Each job in a workflow has its own `steps` section.
    steps:
      # The `uses` key tells the job to retrieve the action named `actions/checkout`. This is an action that checks out your repository and downloads it to the runner, allowing you to run actions against your code (such as testing tools). You must use the checkout action any time your workflow will use the repository's code or you are using an action defined in the repository.
      - name: Checkout
        uses: actions/checkout@v4

      # This step uses the `actions/setup-node` action to install the specified version of the Node.js software package on the runner, which gives you access to the `npm` command.
      - name: Setup node
        uses: actions/setup-node@v4
        with:
          node-version: 16.13.x
          cache: npm

      # The `run` key tells the job to execute a command on the runner. In this example, `npm ci` is used to install the npm software packages for the project.
      - name: Install
        run: npm ci

      # This step uses the `trilom/file-changes-action` action to gather all the changed files. This example is pinned to a specific version of the action, using the `a6ca26c14274c33b15e6499323aac178af06ad4b` SHA.
      # 
      # In this example, this step creates the file "${{ env.HOME }}/files.json", among others.
      - name: Gather files changed
        uses: trilom/file-changes-action@a6ca26c14274c33b15e6499323aac178af06ad4b
        with:
          fileOutput: 'json'

      # To help with verification, this step lists the contents of `files.json`. This will be visible in the workflow run's log, and can be useful for debugging.
      - name: Show files changed
        run: cat $HOME/files.json

      # This step uses the `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes all the parameters it needs to run.
      - 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

      # This step also uses `run` command to execute a script that is stored in the repository at `script/rendered-content-link-checker.mjs` and passes a different set of parameters.
      - name: Link check (critical, all files)
        run: |
          ./script/rendered-content-link-checker.mjs \
            --language en \
            --exit \
            --verbose \
            --check-images \
            --level critical

下一步