github-actions

GitHub Actions

概述

GitHub Actions 是一个 CI/CD 平台，可直接通过 GitHub 仓库自动执行构建、测试和部署流水线。工作流是 .github/workflows/ 中的 YAML 文件，可由推送、拉取请求、定时任务或手动触发等事件启动。每个工作流包含一个或多个作业，由 GitHub 托管或自托管的运行器执行。

适用场景： 自动化测试、持续部署、发布自动化、定时任务、多平台构建、依赖项更新、容器发布、代码质量检查、安全扫描。

不适用场景： 长时间运行的服务（使用合适的托管平台）、超出运行器限制的高强度计算任务（作业超时为 6 小时）、需要在多次运行之间保留状态的任务（使用外部存储）、实时事件处理（使用服务器配合 Webhook）。

快速参考

模式	语法 / 操作	要点
推送触发	on: push: branches: [main]	按分支、路径或标签筛选
PR 触发	on: pull_request: types: [opened, synchronize]	默认包括 opened、synchronize、reopened
定时触发	on: schedule: - cron: '0 6 * * 1'	仅限 UTC，最短间隔为 5 分钟
手动触发	on: workflow_dispatch: inputs:	为手动运行定义带类型的输入
作业依赖	needs: [build, test]	按顺序或并行运行作业
条件作业	if: github.ref == 'refs/heads/main'	基于表达式筛选作业 / 步骤
矩阵策略	strategy: matrix: node: [18, 20, 22]	为每种组合生成作业
依赖项缓存	actions/cache@v5	基于哈希的键，并以 restore-keys 作为回退方案
使用缓存进行设置	actions/setup-node@v6 搭配 cache: 'pnpm'	为包管理器内置缓存
上传制品	actions/upload-artifact@v4	在作业间共享数据或保留输出
下载制品	actions/download-artifact@v4	获取先前作业中的制品
可复用工作流	uses: ./.github/workflows/reusable.yml	通过 workflow_call 触发器调用
复合操作	action.yml 中使用 using: composite	将多个步骤打包为一个操作
并发	concurrency: group: ${{ github.ref }}	取消或排队处理重复运行
环境机密	${{ secrets.API_KEY }}	按仓库、组织或环境限定作用范围
OIDC 身份验证	permissions: id-token: write	为云服务提供商提供短期令牌
步骤输出	echo "key=value" >> "$GITHUB_OUTPUT"	在步骤和作业之间传递数据
服务容器	services: postgres: image: postgres:16	用于集成测试的辅助容器
超时	timeout-minutes: 30	挂起的作业或步骤快速失败
证明材料	actions/attest-build-provenance@v3	用于供应链的 SLSA 构建来源证明

表达式和上下文

上下文	示例	描述
github	github.ref_name, github.sha	事件元数据、仓库信息、操作者
env	env.NODE_ENV	当前作用域的环境变量
secrets	secrets.API_KEY	加密密钥（在日志中会被遮蔽）
inputs	inputs.environment	工作流分发或可重用输入
matrix	matrix.node	当前矩阵组合的值
steps	steps.build.outputs.version	之前步骤的输出
needs	needs.prepare.outputs.tag	依赖作业的输出
runner	runner.os, runner.arch	Runner 环境信息
vars	vars.DEPLOY_URL	仓库或组织配置变量

常见错误

错误	正确做法
使用过时的 Action 主版本	固定到当前主版本（@v6）或提交 SHA
缺少 persist-credentials: false	使用自定义令牌或 OIDC 时，在 checkout 中设置
在工作流级别设置宽泛的 permissions	在工作流级别设置 permissions: {}，按作业授予权限
缓存键未包含依赖文件哈希	在缓存键中包含 hashFiles('**/pnpm-lock.yaml')
在 if: 条件中使用密钥	不能在 if: 表达式中直接使用密钥
不谨慎地使用 pull_request_target	绝不要通过 pull_request_target 以写入权限运行 PR 代码
不取消过时的运行	使用 concurrency 和 cancel-in-progress: true
将结构化数据存储为单个密钥	为每个值单独创建密钥，以便正确地在日志中遮蔽
引用未通过 SHA 固定的 Action 标签	将第三方 Action 固定到完整提交 SHA，确保供应链安全
在脚本中硬编码 Runner OS	使用 runner.os 上下文以确保跨平台兼容性
使用 actions/cache 时未提供 restore-keys	始终提供 restore-keys，以匹配部分缓存
在 run: 块中插入用户输入	通过 env: 传递不可信值，以防止脚本注入
作业未设置 timeout-minutes	设置明确的超时时间，以便卡住的进程能快速失败
未限定范围地使用 always()	与状态检查结合使用：if: always() && steps.x.outcome == 'success'

委派

• 工作流调试：使用 Explore Agent 检查工作流运行日志
• 安全审计：使用 Task Agent 检查权限和密钥用法
• 代码审查：将工作流 PR 审查委派给 code-reviewer Agent

参考资料

• 工作流语法、触发器、作业、步骤和并发
• 缓存策略和构件管理
• 矩阵策略、可重用工作流和复合操作
• 安全、密钥、OIDC 和权限强化