github-actions-runtime-upgrade-conventions

GitHub Actions 运行时升级约定

在编辑 GitHub Actions 工作流以处理有关 action 运行时的弃用警告（例如 Node.js 运行时迁移）时，请使用本技能。

何时使用本技能

• 工作流日志报告某个 action 正在已弃用的运行时上运行。
• 你正在升级 .github/workflows/*.yml 或 .github/workflows/*.yaml 中的 action 版本。
• 你需要在实现 action 依赖现代化的同时保持现有工作流行为不变。

升级规则

• 优先升级到每个 action 与工作流兼容的最新稳定主版本。
• 优先使用不可变固定：将目标发布解析为完整提交 SHA，并在 uses: 中使用该 SHA。
• 在最终建议中，不要固定到可变标签或分支（例如 @v4 或 @main）。
• 每次提交升级一个 action（或一组紧密相关的 action），以便轻松隔离故障。
• 在升级运行时/依赖 action 时，保持现有工作流行为不变。

本仓库跟踪的 Actions

当出现警告时，优先审查以下组的运行时：

• actions/* 下的任何第一方 action
• 尤其是 actions/setup-* 下的 setup action（例如 setup-node、setup-python、setup-dotnet）
• 工作流日志中运行时弃用警告明确指出的任何其他 action

固定模式

steps:
  - uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.3.1
  - uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d1f8 # v4.0.4

在推荐升级时，先确定最新的兼容发布，然后使用对应的提交 SHA，并可选添加版本注释。

验证清单

更改 action 版本后：

1. 确保所有已编辑的工作流仍能解析，并保持相同的触发器/权限，除非有意更改。
2. 运行受影响的工作流（或等效的本地构建/测试命令），并确认升级后的步骤成功完成。
3. 在适用的情况下，确认发布/签名/制品步骤仍产生预期输出。
4. 检查工作流运行日志，查看是否有任何新的弃用警告或运行时迁移说明。

PR 说明

在 PR 摘要中包含：

• 升级了哪些 action（从 -> 到）。
• 是否有任何 action 无法迁移到新的主版本，以及原因。
• 重新运行了哪些工作流以验证更改。

本技能如何补充 Dependabot

Dependabot 可以自动执行许多更新，但在以下情况下，本技能仍然有帮助：

• 仓库中的工作流未启用 Dependabot。
• 运行时警告在自动化更新可用之前出现。
• 工作流在 action 升级后需要进行行为保持验证。