github-actions

GitHub Actions

将工作流视为带有凭据的生产代码。以信任边界为安全依据，以关键路径为性能依据，以执行图为正确性依据。有意识地保留行为，并验证变更路径。

流程

首先选择所有请求的模式：

• **审计：**仅选择此模式时，只检查并报告，不做修改。
• **修改：**诊断并更改现有工作流或 Dependabot 配置。
• **创建：**添加新的工作流、可复用工作流或 Dependabot 配置。

模式可以组合。对于审计并修复的请求，先进行审计，再修改已获授权的发现，并报告已修复和仍待处理的发现。

选择模式后，Dependabot 专属任务请使用 Dependabot 和依赖自动化 中的专用流程。下方的工作流执行图流程仅适用于由 Dependabot 触发的仓库工作流，或为依赖提交生成的工作流。

1. 梳理受影响的流水线

对于现有工作流，遍历所有可到达的本地 Action 和可复用工作流。按不可变标识去重源码读取，但要分析每条调用边及其调用方的 ref、输入、密钥、权限上限、条件、环境和运行器。当可复用契约可能发生变化时，找出所有受影响的调用方。对于创建任务，梳理仓库约定，以及请求行为所暗示的候选组件。

对于每个受影响的执行分支，确定：

• 事件、执行者、refs、分叉仓库和 Dependabot 行为、审批与挂起门槛、默认分支语义，以及适用的 Actions 策略
• 每个作业所使用的代码、表达式、构件、缓存、输入和网络数据
• 每个作业获得的令牌权限、密钥、OIDC 声明、环境和运行器访问权限
• 作业和步骤图，包括 needs、条件、输出、矩阵、后台生命周期、并发和取消
• 包管理器、锁文件、脚本、运行时版本、运行器标签和现有 CI 约定
• 必需检查、部署顺序、发布保证，以及用户依赖的行为
• 对于性能或成本相关工作，满足目标和基线门槛；对于成本工作，还要收集并归因证据

一旦观察到的上下文符合锚定参考的条件，就立即加载：

观察到的上下文	加载内容
参与者可以利用权限影响作业	信任边界图 和 令牌权限
特权事件或默认分支事件会处理参与者的影响	特权事件
外部依赖项、检出操作、本地 ./ 或 $/ 操作或工作流策略会产生影响	依赖项与工作流治理
机密、OIDC、环境或云凭据会产生影响	机密、OIDC 与环境
工件或缓存会跨作业、工作流、引用或信任级别传递，或者 Actions 保留设置发生变化	工件晋级 或 缓存投毒链
自托管运行器或 Actions 策略会产生影响	运行器与网络可达性 或 平台执行保护
运行被挂起、等待批准，或在作业启动前被阻止	审批关卡与挂起的运行；如果是策略拒绝，则参阅平台执行保护
创建、修改或审查 run: 代码块	Shell 语义、表达式边界、失败处理和工作流数据
run: 代码块写入临时文件	由运行器管理的临时存储
使用 GitHub API、gh 或 github-script	选择范围最小的 API，然后参阅对应的接口章节
通过 API 发送 workflow_dispatch，或必须跟踪其运行	工作流分派
将机密扫描自定义模式自动化	机密扫描自定义模式
Dependabot 配置、警报、依赖关系图、依赖项提交、私有注册表或 Dependabot 拉取请求行为会产生影响	Dependabot 与依赖项自动化
使用输出、环境写入或摘要	工作流通道
事件、筛选器、表达式、失败、取消或超时会产生影响	事件与引用、表达式或失败
并发、矩阵或可复用契约会产生影响	并发、矩阵或可复用工作流
延迟、成本、并行度、设置、运行器、缓存或工件会产生影响	明确目标与基线，然后参阅对应的性能章节
Actions 指标、账单报告、仪表板或 GitHub 生成的工作流会产生影响	收集并归属证据
**完成标准：**已选择所有请求的模式；已考虑每个受影响的工作流、调用方、可到达的本地依赖项和不同的调用上下文；已映射每个入口、执行边、能力和行为约定；每项 Dependabot 任务均满足其依赖项范围门槛；性能工作满足其关联的目标与基线门槛。

2. 构建安全的执行图

针对每个选定模式，将映射出的图与下方目标进行比较。在仅审计模式下，记录有证据支持的差异，不进行编辑。对于修改或创建，构建此目标；若同时执行审计，则保留这些差异，作为变更依据：

• 选择能够提供所需上下文且权限最低的事件。
• 建立默认拒绝的令牌基线，并仅授予每个任务所需的权限。
• 限制进入特权操作的不可信值，确保它们无法控制执行、权限选择、目标位置或副作用范围。
• 仅添加数据、隔离或生命周期边；依赖关系允许时，尽早启动独立工作。
• 明确规定必需检查、失败、重试、超时、取消和并发语义。
• 为部署和发布设置受保护环境、不可变输入和经过审慎规划的排队机制。
• 使用锁定的依赖项安装方式，并在脚本有所依赖时明确指定 shell 语义。
• 按照下方的验证流程，使每个外部依赖项都不可变。
• 根据关联的目标和基线设计性能变更，并考虑启动、计算、缓存和制品传输工作。

**完成标准：**每项选定的审计都已将映射出的每条边与所有已加载规则进行比较；每项选定的修改或创建都有目标图，且其中的能力、信任边界跨越、顺序、必需结果和部署语义均有充分依据；性能设计已根据证据说明预期影响，可供验证。

3. 执行所有选定模式

审计

按影响程度排序记录发现项。在仅审计模式下，不进行编辑，直接返回发现项。审计与修改结合时，在最终报告中将每项发现标记为已纠正或待解决。每项发现均包括：

• 严重程度和精确的 file:line
• 触发事件、参与者或输入
• 具体的故障、权限或性能路径
• 最小且安全的纠正措施
• 验证证据或明确的证据缺口

安全问题必须指出从不可信影响到某项能力的具体路径。将纵深防御和风格层面的加固分别标注。性能问题必须指出经测量的瓶颈，或明确标注为关键路径模型。若已无待解决的发现项，请明确说明。

修改

从观察到的行为着手。沿着触发条件、输入、执行路径和结果追踪每个问题。在问题源头以最小且协调的变更加以纠正。除非包管理器、锁文件、运行器、命名或工作流约定导致问题，否则应予以保留。可复用工作流的约定发生变更时，更新所有受影响的调用方。

创建

构建满足所请求行为的最小执行图。优先复用既有的本地操作、可复用工作流、包命令和命名方式，避免引入第二套约定。起草后，重新映射生成的图，并加载所有新匹配的参考资料。

外部引用发生变化时

将新增的操作、可复用工作流、容器映像或显式升级视为依赖项变更：

1. 确定预期版本，并阅读其发行说明和迁移指南。

2. 通过操作或可复用工作流自身仓库的提交端点解析标签，以便带注释的标签能解析为提交 SHA：

   repo='OWNER/REPOSITORY'
   tag='REVIEWED_RELEASE'
   gh api "repos/$repo/commits/$tag" --jq .sha
   gh api "repos/$repo/releases/tags/$tag" --jq '{tag_name,html_url,body}'
   

3. 验证 SHA 属于该仓库；检查与此工作流相关的源代码行为、操作元数据、运行时和 Runner 最低版本要求、权限及输入处理。在 GitHub.com 上，JavaScript 操作只能在 Node 24 上运行，Node 20 的退出选项已取消：将仍声明 runs.using: node20 的版本替换为兼容 Node 24 的版本，并将运行 macOS 13.4 或更早版本，或使用 ARM32 的自托管 Runner 视为不受支持。

4. 按摘要固定容器映像。在未接入锁定文件的工作流之外，将 uses: 设为经过审核的 SHA；凡是 uses: 使用 SHA 的地方，都要同时更新它和面向人的版本说明注释。

5. 如果仓库跟踪 .github/workflows/actions.lock，请检查受影响的工作流是否出现在其 workflows 部分中。对于已接入的工作流，按仓库现有格式更改 uses:，并使用 gh actions-lock <workflow-path> 重新生成其条目，而不是编辑锁定文件；不带路径运行也会清理条目并重写其扫描的每个工作流。以同样方式接入新工作流。常规运行会保留现有条目，因此只有使用 --relock，分支或部分版本固定（例如 @main 或 @v4）才会更新。如果锁定的提交在上游已不可达，--relock 会报错且不写入任何内容；在添加 --accept-moved 前，请先核实上游历史。保留该工具对 uses: 的重写：它可能会将浮动标签替换为所锁定的确切版本，并将可解析的 ./ 操作转换为 $/，这会改变代码来源（参见本地操作引用）。接入前，请修复运行会保留的任何 ./ 操作引用（将其迁移为 $/、修正其路径，或移除该步骤），或只传入其他工作流路径。文档称此类工作流会被跳过，但之后仍要检查 workflows 部分：空条目会将一个无依赖项的工作流接入，而 GitHub 随后会拒绝其远程操作。在工作流及其条目接入之前，第 4 步仍适用于该工作流。在已接入的工作流中，遗留的 ./ 操作引用会导致阻断错误：运行不会写入任何内容，因此请在重新生成前将其迁移为 $/、修正其路径或移除该步骤。检查完整差异，确认每个更改后的 commit 都是经过审核的 SHA；在接受更改后的 owner_id 或 repo_id 前，将其作为可能发生转移或替换的情况进行调查，然后运行 gh actions-lock --verify。

显式升级授权其指定的兼容升级。处理无关工作时，保留现有版本，除非某个版本阻碍所请求的行为，或存在相关安全缺陷。

只有每个所选模式门槛都通过，才算完成：

• **审计：**评估每条已映射边和每条已加载规则，并提供有证据支持的发现，或明确说明未发现问题。
• **修改：**在源头修正每项请求的行为，更新受影响的调用方，并重新映射生成的图。
• **创建：**在最小且符合要求的图中实现每项请求的行为，并重新映射生成的图。
• **依赖项变更：**每个已更改的引用和锁定文件条目都解析到经过审核的不可变对象，且其运行时契约仍保持兼容。
• **Dependabot：**每个受影响的依赖项范围和自动化平面都符合 Dependabot 标准。

4. 验证工作流

1. 运行仓库配置的工作流 lint 命令；否则，对每个受影响的工作流运行 actionlint。Linter 可能落后于当前语法：actionlint 1.7.12 会拒绝有效的 $/ 引用、parallel、background、wait、wait-all、cancel、queue: max、cache-mode、vulnerability-alerts 权限、job.workflow_* 上下文以及 ubuntu-26.04 等新运行器标签。请根据当前 GitHub Docs 核实这些错误，保留有效语法，并报告 linter 版本和差异；修复其他所有问题。
2. 对于已修改的本地操作，使用配置的架构工具验证其元数据（在 GitHub.com 上，JavaScript 操作应声明 runs.using: node24），并测试其声明的输入、输出、入口点、后置行为和具有代表性的调用方。
3. 运行每个已配置的 Actions 安全分析器，并对照信任边界图核对其输出；静态分析是路径追踪的补充。
4. 使用仓库锁定的依赖状态，运行已更改 run: 步骤中的安全底层命令。发布或部署命令应使用有文档记录的试运行模式。
5. 对于性能改动，满足性能标准。将无法访问的远程执行报告为具体的测量缺口。
6. 对于 Dependabot 和工作流的组合改动，还需满足 Dependabot 验证和标准。
7. 重新检查完整的受影响依赖图：事件、审批、暂停和策略语义；权限、机密、OIDC、环境和运行器；依赖固定；本地和可复用的契约；输出、矩阵、缓存、制品、并发、后台屏障和 needs。
8. 报告确切的命令和结果。将不可用的运行器、凭据、服务、策略或工具明确列为验证缺口。

**完成条件：**每个受影响的工作流、已修改的操作清单和已修改的 Dependabot 配置都通过适用的验证，或有明确的工具阻碍；每项更改的行为都有直接执行证据，或有明确的外部阻碍；每项安全结论都注明追踪过的路径；每项优化都满足链接中的性能标准。