配置 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 终结点 /repos/{owner}/{repo}/dispatches 发送 POST 请求，请求正文中包含 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]

使用条件关键字

在工作流文件中，可以访问上下文信息和计算表达式。虽然表达式通常与工作流文件中的条件 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。