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_request | PR 打开、同步、重开 | PR 分支合并到基线的结果 | 以为它能看到仓库密钥(fork 场景下看不到) |
pull_request_target | 同上,但在基线上下文运行 | 基线代码 | 在里面 checkout PR 代码并执行,等于把密钥交给对方 |
workflow_dispatch | 手动点按钮 | 选中分支 | 参数不设 required,跑起来才发现是空的 |
schedule | cron,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 存取一个目录」。三条规则必须先知道:
- 缓存一旦写入就不可修改。同一个 key 第二次保存会失败,提示
Cache already exists。 - 缓存在分支之间有作用域:分支自己写的缓存,只有它自己和它的子分支能读;默认分支的缓存所有分支都能读。
- 一个仓库默认 10 GB 上限,7 天没被访问的条目会被清掉。
所以 key 不能写死。常见写法是把依赖清单的哈希拼进去,依赖一变 key 就变,不会读到过期的包:
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 顶部显式写一段:
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 各管一段
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 汇总,第二次全部命中缓存):
第一次 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
每个服务都要「构建 + 推镜像」,抽成一个可复用工作流:
# .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 }}调用方只有五行:
jobs:
image:
uses: ./.github/workflows/build-image.yml
with:
image: team/demo-api
secrets:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}运行结果(调用方的 job 视图,steps 折叠在可复用工作流内部):
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:
# .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运行结果(命中时的日志):
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
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运行结果:
{
"UserId": "AROAXXXXX:gha-1839201744",
"Account": "123456789012",
"Arn": "arn:aws:sts::123456789012:assumed-role/gha-deploy/gha-1839201744"
}UserId 里那段 gha-1839201744 就是 role-session-name,等于给每次部署打了个可追查的记号。云侧的信任策略要带上条件,只认主分支:
"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)