GitHub Actions 怎么设置构件保留时间

GitHub Actions 的构件保留时间可以分两层设置：仓库级设置决定新构件和日志的默认保留期，工作流里的 retention-days 则可以为某个新上传的构件指定单独期限。排查“改了却没生效”时，先确认改的是构件而不是缓存，再检查上级组织或企业是否限制了最大天数。

仓库统一配置的入口是 Settings → Actions → General。如果只想缩短某个安装包、测试报告或覆盖率文件的保留时间，就在 actions/upload-artifact@v4 的 with 区块加入 retention-days。

步骤一：进入仓库的 Actions 保留设置

打开目标仓库，选择顶部的 Settings。在左侧导航中依次点击 Actions、General，然后向下找到保留期设置。GitHub 当前页面可能把它显示为构件与日志保留，也可能把检查、工作流运行和状态一起写入同一组保留策略；本文只处理 Actions 构件的保留时间。

如果仓库顶部没有 Settings，通常意味着当前账号没有仓库管理员权限。组织仓库还可能受到组织或企业策略约束，这会直接限制仓库能填写的最大天数。

步骤二：填写默认天数并保存

在保留期字段中输入需要的天数，然后点击 Save。GitHub 官方文档给出的范围是：公开仓库可设置 1 到 90 天；私有仓库可设置 1 到 400 天。受组织或企业管理的仓库，实际可填上限不能超过上级策略。

默认保留期是 90 天。这里最容易误判的一点是：新值只对保存之后创建的新构件和日志生效，不会追溯改变已经存在的构件。因此，刚保存后去查看旧运行，旧构件仍显示原来的生命周期并不代表设置失败。

保存后不要只看页面是否出现提示，还要刷新一次设置页，确认输入框仍保留新值。如果保存按钮不可用、字段被锁定或输入较大数字时报错，应到组织或企业的 Actions 策略中检查上限，而不是反复修改工作流。

步骤三：用 retention-days 控制单个构件

仓库默认值适合统一管理，但调试包、临时测试报告往往不需要保留那么久。可以在上传构件的步骤里增加 retention-days。下面示例把覆盖率报告保留 7 天：

# 上传覆盖率报告，并仅保留 7 天
- name: Upload coverage report
  uses: actions/upload-artifact@v4
  with:
    name: coverage-report
    path: coverage/
    retention-days: 7

retention-days 的值不能超过仓库、组织或企业设置的上限。实际使用时，可让正式发布包沿用仓库默认值，而把可重新生成的测试报告设为更短期限，减少无意义的长期存储。

步骤四：触发新运行并确认设置生效

提交工作流文件后触发一次新的运行，打开 Actions，进入对应的运行详情。确认上传步骤成功，并在运行详情的构件区域看到新生成的 coverage-report。核对时只看新运行，因为仓库级修改和 retention-days 都不会替旧构件重写到期时间。

如果上传步骤失败，先检查 YAML 缩进、path 是否能匹配到文件，以及天数是否超过上级上限。若构件上传成功但生命周期不符合预期，则依次比较单构件的 retention-days、仓库默认值、组织上限和企业上限，越上层的最大限制优先。

构件保留与缓存保留不要混淆

构件和缓存虽然都用于工作流，但生命周期规则不是一回事。看到缓存 7 天或缓存容量限制时，不要据此判断构件的到期时间。

常见问题

为什么设置为 30 天，旧构件还是原来的期限？

因为仓库保留策略不追溯已有对象。保存设置后重新运行工作流，新上传的构件才会使用新的默认值或工作流中的单独值。

retention-days 可以比仓库默认值更长吗？

它不能突破仓库、组织或企业设置的最大上限。为了让策略容易理解，实践中通常把单构件值用于缩短临时文件的期限。

组织仓库为什么不能保存 400 天？

公开仓库本身上限是 90 天；私有仓库即使允许更长时间，也仍会受组织或企业策略限制。先确认仓库可见性，再检查上级保留政策。