GitHub Actions artifact retention 怎样按作业设置保存期限

如果一个工作流同时产出测试报告、构建包和临时日志，不必让它们共享同一个保存期限。GitHub Actions 可以在仓库级设置默认值，也可以在具体的 actions/upload-artifact 步骤中用 retention-days 单独指定天数。最实用的做法是：短期调试产物设置较短期限，发布候选包按团队规则保留更久，并先确认仓库、组织或企业策略允许这个值。

官方地址：https://docs.github.com/en/actions/tutorials/store-and-share-data

仓库设置说明：https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository

先确认保存期限的控制层级

打开目标仓库，依次进入 Settings → Actions → General，找到 artifact 与日志保存期限相关的设置。这里的数值是仓库级默认策略，适合为没有单独声明期限的上传步骤提供兜底。

设置单个作业前先记住三个边界：

• 上限优先：retention-days 不能超过仓库、组织或企业策略允许的最大天数。
• 只影响新对象：修改默认值不会把已经上传的 artifact 重新计算一遍。
• 作用对象不同：artifact、工作流日志、工作流运行记录的保存策略不要混为一个字段。

在指定作业里加入 retention-days

编辑工作流文件中的上传步骤。下面的例子让构建作业上传一个保存 7 天的压缩包；中文注释说明了期限和目录的含义，复制时可按项目实际目录替换。

name: build

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build package
        run: |
          # 生成供后续上传的构建目录；实际项目可替换为自己的构建命令
          mkdir -p dist
          printf 'build output\n' > dist/app.txt

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          # 用固定名称便于在运行详情中找到这份产物
          name: build-package
          # 只上传构建目录，避免把临时缓存一起长期保存
          path: dist/
          # 这一步的 artifact 保存 7 天，不能超过上层策略上限
          retention-days: 7

关键字段只有三个：name 是运行详情里看到的产物名称，path 决定上传哪些文件，retention-days 决定这份 artifact 的保存期限。把它放在上传步骤的 with 下，而不是作业顶层；这样同一个作业可以为不同产物采用不同期限。

用不同期限区分构建包和测试报告

当一个作业同时生成可发布包和测试报告时，可以把期限拆开。发布候选包保留 30 天，测试报告只保留 5 天，既方便回溯又能控制存储量。

      - name: Upload release candidate
        uses: actions/upload-artifact@v4
        with:
          # 发布候选包需要给测试和回滚留出更长窗口
          name: release-candidate
          path: dist/release/
          retention-days: 30

      - name: Upload test report
        uses: actions/upload-artifact@v4
        with:
          # 测试报告用于短期排查，避免和发布包使用同一保存期限
          name: test-report
          path: reports/
          retention-days: 5

如果组织策略最多只允许 14 天，那么上面的 30 天并不会突破这个上限；应先在仓库或组织设置中确认可用范围，再把长期产物的天数写入工作流。对需要永久归档的发布文件，不要把 artifact 当成唯一归档介质，应转移到团队认可的发布或存储流程。

运行后在哪里确认结果

提交工作流文件后运行对应作业，打开该次 workflow run，进入作业详情或 Artifacts 区域，先确认上传步骤为成功，再确认 artifact 名称与预期一致。下面的界面说明图展示了“构建作业成功、产物已上传、保存 7 天”的目标状态。

需要查询更精确的删除时间时，可以使用 GitHub Actions artifact REST API 返回的 expires_at 字段。它适合写入内部报表或排查“为什么今天还能下载、明天却找不到”的问题，但不要用页面上的上传时间代替到期时间。

保存期限不符合预期时这样排查

把“上传失败”“保存期限受限”和“到期清理”分成三类处理，定位会比反复修改天数更快。若只想调整新构建的期限，直接改工作流中的 retention-days；若所有作业都需要统一兜底，再调整仓库级设置。

一份可直接执行的设置清单

1. 在 Settings → Actions → General 查看仓库级保存期限和上层限制。
2. 为每个需要独立生命周期的上传步骤设置 name、path 和 retention-days。
3. 提交后运行工作流，确认上传步骤成功且 artifact 名称正确。
4. 长期发布物不要只依赖 artifact，按团队规则进入正式归档流程。
5. 遇到到期时间争议时查 API 的 expires_at，并确认关联 workflow run 是否仍存在。

常见问题

retention-days 可以写 0 吗？

不要把 0 当成“永久保存”或“立即删除”的通用开关。应使用 GitHub 当前文档允许的天数范围，并以仓库、组织和企业策略实际接受的值为准。

修改仓库级保存期限会影响历史 artifact 吗？

不会自动追溯修改已有对象。它主要为之后创建的 artifact 和相关日志提供默认策略；历史对象仍按创建时的规则处理。

为什么 retention-days 写了很大值却没有生效？

先检查上层策略上限，再检查 YAML 中字段是否位于对应上传步骤的 with 下。若仍不确定，查看该 artifact 的到期字段和运行关联关系。