配置 GitHub Actions 工作流

10 分钟

本单元介绍工作流文件中的一些常见配置。你也可以浏览事件类型的类别、禁用和删除工作流，以及使用特定操作版本获得安全性最佳做法。

将工作流配置为运行计划事件

如前文所述，你可以将工作流配置为在 GitHub 上发生特定活动时运行、在 GitHub 外部发生事件时运行，或者在计划的时间运行。通过 schedule 事件可以使用 POSIX cron 语法触发工作流，以在特定 UTC 时间运行。此 cron 语法包含五个 * 字段，每个字段表示一个时间单位。

用于在工作流文件中计划事件的五个时间单位字段的图表。

例如，如果你想每 15 分钟运行一次工作流，schedule 事件应如下所示：

on:
  schedule:
    - cron:  '*/15 * * * *'

如果你想在每周日凌晨 3:00 运行工作流，schedule 事件应如下所示：

on:
  schedule:
    - cron:  '0 3 * * SUN'

此外，你还可以使用运算符来指定值的范围或触发计划工作流。运行计划工作流的最短时间间隔为每 5 分钟一次，这些工作流在默认分支或基本分支上的最新提交上运行。

将工作流配置为针对手动事件运行

除了运行计划事件之外，还可以使用 workflow_dispatch 事件手动触发工作流。通过此事件，可以使用 GitHub REST API 或通过选择 GitHub 上存储库中“操作”选项卡中的“运行工作流”按钮来运行工作流。使用 workflow_dispatch，你可以选择要在哪个分支上运行工作流，还可以设置 GitHub 在 UI 中以窗体元素显示的可选 inputs。

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'

除了 workflow_dispatch 之外，你还可以使用 GitHub API 触发名为 repository_dispatch 的 Webhook 事件。通过此事件，可以触发在 GitHub 外部发生的活动的工作流。它实质上充当存储库的 HTTP 请求，要求 GitHub 从操作或 Webhook 触发工作流。使用此手动事件需要执行两项操作：向GitHub 终结点 POST 发送 /repos/{owner}/{repo}/dispatches 请求，请求正文中包含 Webhook 事件名称，以及将工作流配置为使用 repository_dispatch 事件。

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

将工作流配置为针对 Webhook 事件运行

最后，可以将工作流配置为在 GitHub 上发生特定 Webhook 事件时运行。可以从 Webhook 的多个活动触发大多数 Webhook 事件。如果 Webhook 存在多个活动，则可以指定要触发工作流的活动类型。例如，可以为事件运行工作流 check_run ，但仅适用于 rerequested 或 requested_action 活动类型。

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch 是 GitHub Actions 中的自定义事件，它允许外部系统（甚至其他 GitHub 工作流）通过向 GitHub API 发送 POST 请求来手动触发工作流。它实现灵活的自动化，并能与需要启动存储库中工作流的外部工具、脚本或系统集成。

用例

从外部 CI/CD 工具触发工作流。
协调多存储库部署（例如，存储库 A 完成构建→触发存储库 B）。
基于外部事件（Webhook、监视警报、GitHub 外部的 CRON 作业）启动自动化。
在存储库或单一存储库之间链接工作流执行。

侦听 repository_dispatch 的示例工作流

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

关键元素：

类型：可选。定义自定义事件类型，例如运行测试、部署到 prod 等。
github.event.client_payload：访问调度事件中传递的任何其他自定义数据。
github.event.action：所发送事件类型的名称。

通过 API 触发事件

必须将 POST 请求发送到 GitHub REST API v3 终结点：

POST https://api.github.com/repos/OWNER/REPO/dispatches

授权

需要具有存储库范围的个人访问令牌 (PAT)。
对于组织，请确保令牌的访问设置正确。

示例命令结构

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

有效负载结构

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

参数

领域	类型	DESCRIPTION	必选
`event_type`	字符串	事件的自定义名称。这映射到工作流触发器中的类型值	是的
`client_payload`	物体	将自定义数据发送到工作流的任意 JSON 有效负载 (github.event.client_payload)	否
否

Repository_dispatch 参数明细

向 GitHub API 终结点发出 POST 请求时，必须传递包含两个主要参数的 JSON 正文：

事件类型
client_payload

事件类型

这是一个必需的自定义字符串，你定义后，GitHub 会将其视为调度的“动作”或“类型”。它用于标识工作流的触发者并筛选正在侦听特定类型的工作流。

格式：
- 类型：字符串
- 示例：“deploy”、“run-tests”、“sync-db”、“build-docker”
在工作流中使用：用于侦听特定事件类型并访问工作流中的值。这有助于重复使用单个工作流以实现多个目的，并使自动化更加有序和事件驱动。
示例：

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

客户端负载

这是一个自由格式的 JSON 对象，可让你随调度一起发送自定义数据。定义结构，并在工作流中可访问它。

格式：
- 类型：对象
- 自定义键和值
在工作流中使用：用于多环境部署、版本控制发布或从另一个系统或管道传递上下文，并启用参数化工作流，类似于输入参数。
示例：

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

示例负载细分

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

使用条件关键字

在工作流文件中，可以访问上下文信息和计算表达式。虽然表达式通常与工作流文件中的条件 if 关键字一起使用，以确定是否应运行某个步骤，但你可以使用任何受支持的上下文和表达式来创建条件关键字。请务必知道，在工作流中使用条件时，需要使用特定的语法 ${{ <expression> }}。这会告知 GitHub 计算表达式，而不是将其视为字符串。

例如，某个工作流使用 if 条件检查 github.ref（触发了工作流运行的分支或标记引用）是否匹配 refs/heads/main。为了继续，工作流将如下所示：

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

注意，在本示例中，语法中缺少 ${{ }}。对于一些表达式，如 if 条件表达式，可以省略表达式语法。 GitHub 会自动计算其中一些常见的表达式，但你可以始终包括它们，以免你忘记 GitHub 会自动计算哪些表达式。

有关工作流语法和表达式的详细信息，请参阅 GitHub Actions 的工作流语法。

禁用和删除工作流

将工作流添加到存储库后，你可能会发现需要临时禁用工作流的情况。可以在 GitHub 上或通过 GitHub REST API 停止触发工作流，而无需从存储库中删除该文件。如果你希望再次启用工作流，可以使用相同的方法轻松启用。

在 GitHub 上禁用工作流的屏幕截图。

在以下某些情况下，禁用工作流非常有用：

工作流上的错误是产生过多请求或错误请求，对外部服务产生负面影响。
你想临时暂停不重要且占用你太多时间的工作流。
你想暂停正在向已关闭的服务发送请求的工作流。
你正在使用一个分支，并且你不需要它所包含的一些工作流的所有功能（例如计划工作流）。

你还可以通过 GitHub UI 中的“操作”选项卡或通过 GitHub API 终结点 DELETE /repos/{owner}/{repo}/actions/runs/{run_id} 取消正在进行的工作流运行。请注意，当你取消工作流运行时，GitHub 将取消该运行中的所有作业和步骤。

使用组织的模板化工作流

如果组织中有多个团队使用的工作流，则无需为每个存储库重新创建相同的工作流。相反，可以使用组织 .github 存储库中定义的工作流模板来提升整个组织的一致性。组织内的任何成员都可以使用组织模板工作流，并且该组织内的任何存储库都可以访问这些模板工作流。

你可以通过以下方法找到这些工作流：导航到组织内存储库的“操作”选项卡，选择“新工作流”，然后找到组织的工作流模板部分，其标题为“按组织名称创建的工作流”。例如，名为 Mona 的组织具有如下所示的模板工作流。

Mona 的一个名为“greet and triage”的模板组织工作流的屏幕截图。

使用特定版本的操作

在工作流中引用操作时，建议引用该操作的特定版本，而不仅仅是操作本身。通过引用特定版本，你可以防止将意外更改推送到可能会中断你的工作流的操作。下面是几种可以引用特定版本的操作方法：

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

有些引用会比其他引用更安全。例如，引用特定分支将使用该分支的最新更改来运行该操作，这可能是你需要的，也可能不是。通过引用特定版本号或提交 SHA 哈希，你可以更具体地了解正在运行的操作版本。为了获得更高的稳定性和安全性，我们建议在工作流中使用已发布操作的提交 SHA。