GitHub Actions artifacts 怎样只保留指定天数的构建产物

在 GitHub Actions 的上传步骤中填写 retention-days: 7，就能让该步骤创建的 artifact 按七天保留；想统一调整仓库默认值，则进入 Settings → Actions → General 修改保留期。新设置不追溯修改已有产物，所以“改成七天后，旧文件仍在”并不一定是配置失效。

官方地址：https://github.com/

下面以“临时预览包只留七天”为例。示例面向 GitHub.com，使用 GitHub 托管的 Ubuntu runner；GitHub Enterprise Server 的 action 版本支持不同，不应直接照搬。插图均为原创操作说明，不是实际仓库或执行记录。

1. 在仓库设置中确认默认保留期

打开目标仓库，点击 Settings → Actions → General，找到包含 artifact 与 log retention 的保留期区域，输入 7，点击 Save。当前官方文档的完整字段名称是 Check, workflow run, status, artifact and log retention，它的范围比单个构建产物更广。

保存后，重新进入该区域应能看到保存的天数。若没有 Settings、输入框不可编辑或范围受到限制，先确认管理权限以及组织、企业的上级策略，不要通过改工作流来尝试突破上限。只想缩短预览包、保留其他数据原有策略时，可保持仓库默认值不动，直接使用下一步的单产物参数。

2. 给上传步骤填写 retention-days

打开仓库 Code → .github/workflows 中的目标 YAML 文件，编辑负责上传构建产物的步骤，在 with 下加入保留天数，然后通过 Commit changes 保存到用于运行的分支。下面是独立的手动示例，生成一个简单预览说明文件，不依赖某个项目的构建命令。

# .github/workflows/artifact-demo.yml：手动生成并上传七天预览包
name: Artifact retention demo
on:
  workflow_dispatch:
permissions:
  contents: read
jobs:
  upload-preview:
    runs-on: ubuntu-latest
    steps:
      - name: Create preview file
        run: |
          # 示例文件用于展示上传范围，实际项目替换为构建输出
          mkdir -p out
          printf '%s\n' 'Preview bundle for this run' > out/preview.txt
      - name: Upload preview bundle
        uses: actions/upload-artifact@v7
        with:
          name: preview-bundle
          path: out/
          # 此处限定本步骤新上传产物的保留天数
          retention-days: 7
          if-no-files-found: error

当前官方 action 用法示例使用 v7；已有流水线应结合自身 runner 和组织允许列表采用受支持版本。示例不需要 checkout，因为文件直接在 runner 工作目录创建；真实项目通常仍需保留自己的检出与构建步骤。

retention-days 必须放在上传 action 的输入区，不能放到 job 的根层。省略它或填写 0 表示使用默认保留策略，不代表永久保存；指定值应为允许范围内的正整数。此处的 name 决定产物名称，path 决定上传哪些文件，两者都不会代替保留期设置。

保存后在文件页确认提交里仍是 retention-days: 7。如果其他上传步骤也要七天，应分别设置；不要假定一个步骤的输入会成为整个工作流的通用值。

3. 在新运行中找到产物并限定下载范围

文件进入默认分支后，进入 Actions → Artifact retention demo → Run workflow，选择包含该配置的分支并启动。等待上传步骤完成，再点击这次运行的名称进入摘要页，找到 Artifacts → preview-bundle 下载。若没有手动运行按钮，检查默认分支是否包含带 workflow_dispatch 的文件以及当前账号是否有运行权限。

这里应能看到新运行的 preview-bundle，下载后包含 preview.txt。这是读者操作后的预期状态，并非本文已执行的测试结果。不要打开旧运行来判断新配置是否生效；即使产物名称一样，不同运行也是不同的产物对象。

网页下载需要登录并对仓库有读取权限，知道链接不等于获得下载权限。产物过期或被删除后，旧链接也不会让文件继续可用。需要发布给用户长期下载的正式交付物，应采用适合长期分发的存储渠道，不能把短期 artifact 链接作为永久入口。

已有文件与存储占用怎么处理

降低新产物的保留期，有助于减少后续长期堆积，但不会让旧文件立即全部消失，也不能据此承诺账单立刻下降。先减少上传范围，只保存需要交付或排障的文件；大型中间目录没有必要随着每次运行重复上传。

确认旧产物已不再需要后，可以按团队的保留要求单独清理；清理前保留确有需要的副本。artifact 与依赖缓存是不同对象，retention-days 不是缓存的保留开关。若要回退本次修改，恢复仓库原设置，并移除或调整上传步骤的参数；回退也只改变之后新创建对象的策略。

参考：仓库 Actions 设置；upload-artifact 官方输入说明；下载工作流产物。