GitHub Actions：最佳实践

这份_持续维护_的文档汇集了使用 GitHub Actions 的最佳实践。 如果你有任何建议或补充，欢迎在 GitHub 上发起 pull request！

• GitHub Actions：最佳实践
  • 最佳实践汇总
    • 为工作流设置超时
      • 示例
    • 考虑是否真的需要（第三方）action
    • 限制工作流令牌的权限范围
      • 示例
    • 将 action 固定到 SHA
      • 查找提交 SHA
      • 示例
    • 将测试运行器固定到具体版本
      • 示例
    • 考虑配置并发策略
      • 示例
    • 考虑真正需要哪些触发器
    • 阅读“GitHub Actions 安全加固”指南
  • 工作流检查清单

最佳实践汇总

为工作流设置超时

默认情况下，如果工作流在 6 小时内没有完成，GitHub Actions 就会将其终止。 许多工作流根本用不了这么长时间就能完成，但有时会出现意外错误，或者某个任务卡住，直到工作流启动 6 小时后才被终止。 因此，建议指定一个更短的超时时间。

理想的超时时间取决于具体的工作流，但对 Exercism 代码仓库中使用的工作流来说，30 分钟通常绰绰有余。

这样做有以下好处：

• PR 不会在半天里一直等待 CI，问题能被尽早发现，或者可以重新运行工作流。
• 并行构建的总量有限，卡住的任务如果被尽早取消，就不会给其他 PR 带来麻烦。

示例

jobs:
  configlet:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - [...]

考虑是否真的需要（第三方）action

action 应该像你最喜欢的编程语言中的依赖项一样对待¹。它们是由 Exercism 无法控制的第三方作者编写的代码。 即使你信任该 action 的作者，代码仓库也可能被恶意接管，这会间接让那些人获得 Exercism 代码仓库的访问权限，包括写入权限。

因此，你应该仔细考虑引入一个新 action 是否真的值得，或者把代码移入 Exercism 掌控下的一个（新）action 是否更好。

另外，也要考虑这个 action 是否仍在积极维护，例如查看代码仓库近期的活动，或者确认该 action 属于某个组织，而不是个人账号。

由 GitHub 或 Exercism 组织发布的 action，通常可以认为大致安全，无需特别考量即可使用。

限制工作流令牌的权限范围

默认情况下，赋予工作流的访问令牌拥有广泛的权限，既可读取也可写入。

最小权限原则同样应该应用到工作流上。

你可以按工作流分别指定它需要哪些权限。

示例

如果某个工作流只需要读取代码仓库的内容，而不需要写入，例如因为它只是一个普通的 CI 检查，那么你可以按如下方式限制令牌的权限：

permissions:
  contents: read

完整的权限列表请查阅 GitHub Docs。

将 action 固定到 SHA

使用其他 action 时，要把它们固定到某个提交（通过其 SHA），_而不是_分支或标签。 这样可以确保每次执行的都是同一份代码，而固定到分支或标签则无法保证这一点。

这有两个好处：

1. 它让你的构建更加_稳定_
2. 它防止攻击者修改分支或标签，使其指向恶意代码

这条规则唯一的例外，可能是我们（Exercism）自己构建的 action。

查找提交 SHA

通常，你会想固定到某个具体发布版本的提交 SHA。 要找到某个发布版本的提交 SHA，请打开该 action 代码仓库的 releases 页面（例如 https://github.com/actions/checkout/releases）。 找到你想使用的那个发布版本，点击该发布版本左侧摘要区域里列出的简写 SHA（例如 a12a394）。 随后你会被重定向到发布详情页面，那里会列出你可以使用的完整提交 SHA。

示例

- name: Checkout code
  uses: actions/checkout@a12a3943b4bdde767164f792f33f40b04645d846

将测试运行器固定到具体版本

大多数工作流都会运行在 GitHub 支持的运行器上。 使用这些运行器时，请指定一个具体的版本，而不是最新版本。

这样可以确保工作流始终运行在同一个运行器上，让你的构建更加_稳定_。

示例

用：

runs-on: ubuntu-22.04

而不是：

runs-on: ubuntu-latest

考虑配置并发策略

如果在推送了更新的提交之后，再去对中间提交运行 CI，往往既不必要也没什么用。

你可以配置并发策略，从而自动取消同一上下文中正在运行的工作流。

示例

要取消 PR 中的中间构建，可以使用下面的并发设置：

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}

考虑真正需要哪些触发器

阅读“GitHub Actions 安全加固”指南

上面提到的实践并不全面。 关于安全使用 GitHub Actions 的良好实践的完整指南，请查看 GitHub 的安全指南。

工作流检查清单

你可以用下面的检查清单来检查某个工作流是否遵循了这些最佳实践。 这份检查清单并不追求面面俱到，而是聚焦于最重要的条目。