Skip to content

GitHub Actions 工程化实践 ​

本篇要点:把《CICD 入门:从提交到上线的全链路》那条 20 行的流水线,改造成一个团队九个人愿意长期维护、并且不会把云账号钥匙漏出去的样子。 前置文章:《CICD 入门:从提交到上线的全链路》用 shell 和一段 YAML 跑通了「提交即验证」,这一章解决它留下的四个坑。

一、为什么需要它 ​

2026 年 4 月,一个做 SaaS 的团队请人看他们的 CI。.github/workflows 目录下 11 个文件,加起来 3412 行 YAML,其中 8 个是从第一个文件复制出来的,只改了镜像名和部署环境。

后果是每次动公共部分就要改 8 遍。有一次给测试步骤加了 --max-warnings=0,只改了 6 个文件,剩下两个仓库继续放行 ESLint 警告,两个月后两个服务里堆了 40 多条从未被处理过的告警。

比这更贵的是另一件事。他们有个 deploy.yml 用 pull_request_target 触发,目的是「让来自 fork 的 PR 也能拿到部署预览的密钥」。这个写法把仓库密钥暴露给了任何提交 PR 的人:攻击者只要在自己的分支里改一下构建脚本,脚本就会在带密钥的环境里执行。他们是在收到云厂商一张 4300 美元的账单时才发现这件事的。

这两个问题都不是「YAML 写错了」,而是没做工程化:公共逻辑没有复用机制,权限没有边界,凭证没有生命周期。这一章把这四件事逐个说清。

二、核心概念 ​

2.1 触发器:先想清楚「谁在什么条件下跑」 ​

一个 workflow(工作流)由 on: 决定何时运行。常用的几个事件边界差别很大,混用会带来意料之外的空跑和漏跑。

事件触发时机拿到的代码常见误用
push推到分支或 tag推上去的那份不加 branches 过滤,所有分支全量构建
pull_requestPR 打开、同步、重开PR 分支合并到基线的结果以为它能看到仓库密钥(fork 场景下看不到)
pull_request_target同上,但在基线上下文运行基线代码在里面 checkout PR 代码并执行,等于把密钥交给对方
workflow_dispatch手动点按钮选中分支参数不设 required,跑起来才发现是空的
schedulecron,UTC 时区默认分支按北京时间写 cron,整体差 8 小时
workflow_call被别的 workflow 调用调用方指定的忘了声明 inputs 就传参

表 2-1 六种触发事件的边界,第三行是安全事故的高发区

paths 过滤有个容易踩的坑:如果 workflow 因为 paths 不匹配被跳过,而它又是分支保护里要求的检查项,PR 会一直显示「等待中」,永远合不进去。要么把这类检查拆到独立的必过 workflow,要么不用 paths 过滤。

2.2 复用:reusable workflow 与 composite action 的分工 ​

两个机制常被混着用,界线其实很清楚。

可复用工作流(reusable workflow)复用的是一个完整的 job 序列:它有自己的 runner、自己的 job 划分、自己的权限。声明方式是 on: workflow_call,调用方写 uses: ./.github/workflows/build.yml。

复合动作(composite action)复用的是一串 step,跑在调用方的 job 里,共享同一个 runner 和文件系统。它必须放在一个含 action.yml 的目录里,runs.using: composite,每个 step 必须写 shell。

判断方法一句话:要不要独立的 runner、要不要独立的权限,要就是 workflow,不要就是 action。

图 2-1 调用方 workflow、reusable workflow、composite action 三者的嵌套关系

如图 2-1 所示,reusable workflow 在 job 这一层被替换,composite action 在 step 这一层被替换。搞错层级就会出现「我在 action 里设置了 permissions,为什么不生效」——因为权限是 job 的属性,action 改不了。

可复用工作流支持嵌套,最多四层;跨仓库引用写成 org/repo/.github/workflows/x.yml@v1,本地引用写 ./.github/workflows/x.yml。密钥要显式传,或者用 secrets: inherit 一次性继承全部——后者方便,但也把「这个 workflow 到底用到哪些密钥」这个信息抹掉了,密钥超过五个就别用。

2.3 矩阵:把复制粘贴换成一行 ​

矩阵(matrix)把一组参数展开成并行 job。三行配置顶替十份 YAML。

要注意两点。一是 fail-fast 默认为 true,任一组合失败就把其它正在跑的取消掉,排查「到底是 Node 20 挂了还是 Node 22 挂了」时很碍事,跨版本兼容性测试一般设成 false。二是组合数上限 256,超过会直接报错,不是静默截断。

include 用来加特例,exclude 用来减组合。两者同时存在时先应用 exclude 再应用 include,顺序写反是「为什么我的特例没加进去」的常见原因。

2.4 缓存:key 的设计决定命中率 ​

缓存(cache)在 Actions 里是「按 key 存取一个目录」。三条规则必须先知道:

  1. 缓存一旦写入就不可修改。同一个 key 第二次保存会失败,提示 Cache already exists。
  2. 缓存在分支之间有作用域:分支自己写的缓存,只有它自己和它的子分支能读;默认分支的缓存所有分支都能读。
  3. 一个仓库默认 10 GB 上限,7 天没被访问的条目会被清掉。

所以 key 不能写死。常见写法是把依赖清单的哈希拼进去,依赖一变 key 就变,不会读到过期的包:

yaml
key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
  ${{ runner.os }}-npm-

restore-keys 是前缀匹配的回退,它救的是「lockfile 变了但大部分包没变」的场景:精确 key 未命中时,取最近的一个前缀匹配缓存,再在上面增量安装。

2.5 权限最小化与 OIDC:别把长期密钥放进仓库 ​

GITHUB_TOKEN 是每个 job 自动拿到的令牌,生命周期到 job 结束。它的权限由 permissions: 控制,可以在 workflow 级或 job 级设置,job 级覆盖 workflow 级。

默认权限取决于仓库设置,可能是「宽松」(可写 contents)也可能是「受限」。依赖默认值是危险的,因为仓库设置会被随手改。做法是在每个 workflow 顶部显式写一段:

yaml
permissions:
  contents: read

需要什么加什么。要往 Release 传产物才加 contents: write;要评论 PR 加 pull-requests: write。完全不需要就写 permissions: {}。

即便收到最小,GITHUB_TOKEN 也只能操作 GitHub 自己。部署到 AWS、GCP、Azure 还是要一份云上的凭证。传统做法是把 access key 存进仓库 Secret,风险有三个:永不过期、看不到谁在用、泄露后要人工轮换。

OIDC(OpenID Connect)换了个思路:GitHub 在 job 运行时签发一张短期令牌,云厂商验证这张令牌的签名和里面的声明(哪个仓库、哪个分支、哪个 workflow),通过了才临时发放凭证,有效期通常 15 分钟到 1 小时。仓库里一个长期密钥都不用存。

前提是两边的握手:GitHub 侧给 id-token: write 权限,云侧在信任策略里写清「只接受 repo:org/repo:ref:refs/heads/main 这个主体的令牌」。少了后半个条件,任何仓库都能换成你云账号的凭证。

三、动手实践 ​

目标是把《CICD 入门:从提交到上线的全链路》那条 1 分 42 秒、全量重装的流水线,改造成带复用、矩阵、缓存、最小权限和 OIDC 的版本。改造前先记下基线,改造后才有对比。

3.1 主线 workflow:四个 job 各管一段 ​

yaml
name: ci
on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npx eslint . --max-warnings=0

  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        node: [20, 22, 24]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: npm
      - run: npm ci
      - run: node --test

运行结果(同一个 commit 连续跑两次的 job 汇总,第二次全部命中缓存):

text
第一次  ci / lint            Success   58s   (npm ci 31s)
        ci / test (20)       Success  1m12s
        ci / test (22)       Success  1m09s
        ci / test (24)       Success  1m14s
第二次  ci / lint            Success   21s   (npm ci 4s)
        ci / test (20)       Success   34s
        ci / test (22)       Success   32s
        ci / test (24)       Success   36s

三个数字值得记下来。缓存把依赖安装从 31 秒压到 4 秒;fail-fast: false 让三个版本同时跑完,一次就能看全兼容性问题;concurrency 里 cancel-in-progress: true 意味着同一个分支连推三次,前两次会被取消,省下两次全量构建。

3.2 把重复部分抽成 reusable workflow ​

每个服务都要「构建 + 推镜像」,抽成一个可复用工作流:

yaml
# .github/workflows/build-image.yml
name: build-image
on:
  workflow_call:
    inputs:
      image:
        required: true
        type: string
      context:
        required: false
        type: string
        default: "."
    secrets:
      REGISTRY_TOKEN:
        required: true
    outputs:
      digest:
        description: "镜像 digest"
        value: ${{ jobs.build.outputs.digest }}

permissions:
  contents: read
  packages: write

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      digest: ${{ steps.push.outputs.digest }}
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}
      - id: push
        uses: docker/build-push-action@v6
        with:
          context: ${{ inputs.context }}
          push: true
          tags: ghcr.io/${{ inputs.image }}:${{ github.sha }}

调用方只有五行:

yaml
jobs:
  image:
    uses: ./.github/workflows/build-image.yml
    with:
      image: team/demo-api
    secrets:
      REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}

运行结果(调用方的 job 视图,steps 折叠在可复用工作流内部):

text
ci / image    Success   1m26s
  ↳ build-image / build    Success   1m24s
      digest: sha256:9a3c77e1f0b2...

注意 outputs 的跨层传递:job 里先把 step 的输出接到 job 输出,workflow 再把 job 输出接到 workflow_call 的 outputs。少接一层,调用方拿到的就是空字符串。

3.3 用 composite action 复用「一串检查」 ​

同一个仓库里的三个服务都要跑「装依赖 + 抽查密钥硬编码」,这属于 step 级复用,写成 composite:

yaml
# .github/actions/setup-and-audit/action.yml
name: setup-and-audit
description: 安装依赖并扫描硬编码密钥
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: 22
        cache: npm
    - run: npm ci
      shell: bash
    - run: |
        if grep -rInE '(AKIA[0-9A-Z]{16}|ghp_[A-Za-z0-9]{36})' src/; then
          echo "::error::检测到疑似硬编码凭证"
          exit 1
        fi
      shell: bash

运行结果(命中时的日志):

text
Run if grep -rInE ... ; then
src/config/aws.ts:8:export const KEY = "AKIA****"
Error: 检测到疑似硬编码凭证
Error: Process completed with exit code 1.

::error:: 是 GitHub 的工作流命令(workflow command),被它输出的内容会在页面顶部单独列出来,比 echo 更容易被看见。

3.4 把云上密钥换成 OIDC ​

yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write        # 必须,否则拿不到 OIDC 令牌
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          role-session-name: gha-${{ github.run_id }}
          aws-region: ap-northeast-1
      - run: aws sts get-caller-identity

运行结果:

text
{
    "UserId": "AROAXXXXX:gha-1839201744",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/gha-deploy/gha-1839201744"
}

UserId 里那段 gha-1839201744 就是 role-session-name,等于给每次部署打了个可追查的记号。云侧的信任策略要带上条件,只认主分支:

text
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
  },
  "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:myorg/demo-api:ref:refs/heads/main"
  }
}

少了 sub 这一条,同账号下任何仓库的任何分支都能扮演这个角色,等于把门开给了整个组织。

四、常见误解 ​

很多人以为把密钥放进仓库 Secret 就安全了。实际上 Secret 只保证了「不显示在日志里」,挡不住在带密钥的环境里执行别人的代码。pull_request_target 加上 checkout PR 分支,组合起来就是一条完整的攻击路径;fork 来的 PR 默认读不到 Secret,这个默认是有理由的。

很多人以为缓存配了就会快。实际上命中率完全由 key 决定。把 key 写成固定字符串,第一次之后永远命中一份旧缓存,看似很快,实际装的是三个月前的依赖树;把 lockfile 哈希写进 key 又没配 restore-keys,依赖一改就全量重下,命中率掉到零。两种都常见。

很多人以为 permissions: read-all 就够了。实际上 read-all 是把所有只读权限一次性给全,包扫描、议题、组织成员信息都在内。真正的最小权限是白名单,只写你用到的那两三项。

五、小结 ​

《CICD 入门:从提交到上线的全链路》那条流水线能跑,这一章让它能维护。四条改动对应四个坑:

  • 触发器先划边界。pull_request_target 不是「PR 用的 push」,它跑在基线上下文里,配错就是事故。
  • 复用分两层:要独立 runner 和权限用 reusable workflow,只复用 step 用 composite action。跨层设置权限一定不生效。
  • 矩阵解决重复,缓存解决速度。缓存 key 用「系统 + 依赖清单哈希」,再配 restore-keys 兜底。
  • 权限写白名单,云上凭证用 OIDC 换短期的,信任策略里必须限定仓库和分支。

六、相关文章 ​

这套写法在 GitHub 上是顺的,但很多团队的主仓库在 GitLab,那边的组织方式完全不同:没有单独的 workflow 文件,所有 job 挤在一个 .gitlab-ci.yml 里靠 include 和 extends 拆分;触发条件不用事件而用 rules;想并行不靠 job 图自动推导,要手写 needs 做 DAG。更麻烦的是 Runner 要自己养,注册、打标签、按负载伸缩都得自己管。相关文章把这些差异逐条对上,尤其是 rules 和 needs 这两处最容易写错语义的地方。

继续阅读:[《GitLab CI 进阶》 GitLab CI 进阶](/guide/cicd/gitlab-ci-advanced.html)