GitHub Actions 构件保留策略怎样影响流水线

GitHub Actions 构件的保留时间，会决定测试、人工审批、延迟部署和问题追溯还能否取得当时的文件。构建记录显示成功，并不代表文件会永久可下载。流水线需要把“何时上传、下游何时消费、到期如何处理”一起设计；保留期过短，延迟任务可能找不到构件，过长则会积累存储占用。

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

把构件保留时间纳入交付窗口

一条流水线当天完成构建，数天后才批准上线，如果部署依赖那个构件，保留时间就必须覆盖等待期和处理余量。它还应考虑失败调查、回滚和审计需要。临时中间文件与正式交付包有不同生命周期，不宜给所有文件套同一个长期保留值。

GitHub.com 官方文档列出的默认构件和日志保留期是 90 天；公共仓库可配置 1—90 天，私有仓库可配置 1—400 天，实际还受组织或企业上限约束。这是配置范围，不表示每个仓库当前都使用最大天数。工作流上传时也能指定 retention-days，但不能超过有效策略上限。

配置一份有限保留的上传下载示例

下面以 GitHub.com 工作流为例，使用 v4 构件动作接口演示，不把它描述成最新版本。将文件保存为 .github/workflows/artifact-retention-demo.yml，提交到默认分支后，在仓库 Actions 中选择该工作流，通过 Run workflow 手动触发。仓库策略需要允许对应动作；GitHub Enterprise Server 的支持范围应另查部署版本文档。

name: artifact-retention-demo
on:
  workflow_dispatch:

permissions:
  contents: read

jobs:
  produce:
    runs-on: ubuntu-latest
    steps:
      - name: Create demo file
        shell: bash
        run: |
          # 只生成一份演示交付文件，不读取仓库或凭据。
          mkdir -p output
          printf '%s\n' 'artifact retention demo' > output/note.txt
      - name: Upload handoff
        uses: actions/upload-artifact@v4
        with:
          name: demo-handoff
          path: output/note.txt
          # 这里用七天演示，必须满足仓库及上级策略限制。
          retention-days: 7
          if-no-files-found: error

  consume:
    needs: produce
    runs-on: ubuntu-latest
    steps:
      - name: Download same-run handoff
        uses: actions/download-artifact@v4
        with:
          name: demo-handoff
          path: received
      - name: Read demo file
        shell: bash
        run: |
          # 验证同一次运行内的跨任务文件交接。
          test -f received/note.txt
          cat received/note.txt

produce 上传名为 demo-handoff 的构件，consume 通过 needs 等待上传任务完成，再按名称下载同一次运行的文件。两个任务的 runner 文件系统独立，不能只写一个目录就假定另一个任务能读到。retention-days: 7 控制服务端构件保留，而 needs 控制任务依赖，两者不能互相替代。

读者运行后的预期是两个任务均完成，下载步骤写出 received/note.txt，运行详情的构件区出现 demo-handoff。这里给出的是示例预期，未声称已在真实仓库执行。上传步骤使用 if-no-files-found: error，使输出路径缺失成为明确失败，而非只有警告的“成功”流程。

按运行记录定位下载与过期问题

人工下载时，从仓库 Actions → 对应工作流 → 具体运行 → Artifacts 找到构件。查看构件名、生成运行和时间，不能只拿某次成功构建的截图或日志当文件存在的证明。下载还要求相应访问权限；链接存在与当前用户能否读取，是两个问题。

自动化下载同一次运行可使用上面的配置；下载其他工作流或其他运行的构件，需要明确来源运行标识，并提供足够权限的 token 等必要参数。生产消费方应绑定明确的来源运行，而不是含糊地取“最新同名文件”。

当文件不可下载，先区分未曾上传、名称不一致、来源运行选错、访问权限不足、已经过期或被主动删除。到期删除后的构件不能通过延长默认值重新找回；重新构建会产生新运行及新文件，不能无条件当成原交付物。需要长期保留的版本，应在到期前进入有明确生命周期的发布或归档存储，并记录来源版本。

调整默认策略时区分新旧构件

仓库管理入口通常为 Settings → Actions → General，在构件和日志保留相关区域修改天数并保存；界面具体分组名称可能随版本变化。修改默认保留时间只作用于新的构件和日志，不会追溯改写已有对象的保留时间。因此，不能通过改一次设置，就假定历史构件同步延寿或立即按新值清理。

清理时优先识别已被消费且无需追溯的临时文件，保留仍支撑审批或回滚的对象。构件删除会影响所有依赖它的消费者，不应只看创建任务已经结束就立即删除。

常见问题

retention-days 写 0 是永久保留吗？

不是。上传动作将 0 解释为使用默认保留设置；具体上限仍以仓库和上级策略为准。

工作流成功，为什么没有构件？

构件需要显式上传。检查上传步骤是否执行、路径是否存在，以及空路径时动作是警告还是失败。缓存也不能直接当作交付构件。

删除运行记录会不会影响下载？

会影响关联构件的可用性。构件链接的有效性还取决于构件、运行和仓库未被删除，不能当作永久公开下载地址。

构件保留策略最终约束的是文件可用窗口。把有效策略、来源运行、下游消费和到期归档连在一起安排，才能避免“构建成功但交付文件已经消失”的断点。

参考：GitHub 仓库 Actions 保留设置、upload-artifact 官方说明、工作流构件存储与共享。