GitHub Actions REST API下载工件临时URL设计相关疑问

设计原因说明 #

为什么第一次API调用不直接返回工件内容 #

• 架构解耦需求：api.github.com是GitHub统一的API网关层，只负责鉴权、权限校验、请求路由，不实际存储Actions工件二进制数据。工件实际存放在专用的边缘存储节点（即返回的pipelines.actions.githubusercontent.com域名对应的基础设施），网关层没有能力直接返回存储节点上的文件内容。
• 性能与成本考量：如果所有工件下载流量都经过核心API网关，大体积工件会占用大量网关带宽和计算资源，极易触发限流甚至导致网关服务不可用。通过短时效签名URL把下载流量调度到离用户更近的边缘节点，既可以提升下载速度，也能大幅降低核心网关的负载压力，同时对象存储原生支持的断点续传、分片下载能力也不需要在网关层重复开发。
• 安全收敛：短时效签名URL有效期仅1分钟，无需额外鉴权即可访问，核心网关只需要在第一次请求时做一次权限校验，后续下载过程不需要重复执行鉴权逻辑，兼顾安全性和性能；即使签名URL意外泄露，1分钟后就会自动失效，安全风险极低。

为什么临时URL放在Location响应头而非JSON响应体 #

• 符合HTTP标准语义：请求成功时该接口返回标准的302 Found状态码，根据HTTP协议规范，临时重定向的目标地址必须放在Location响应头中。这种设计是HTTP生态的通用约定，所有标准HTTP客户端（包括cURL、浏览器、各类HTTP SDK）都原生支持自动识别该头并跟随跳转，不需要额外编写解析逻辑。
• 兼容性最优：如果把URL放在JSON响应体中，所有客户端都需要额外编写响应体解析逻辑，无法直接使用HTTP客户端自带的重定向跟随能力，反而会提升接入成本。你提到的错误场景返回JSON，是因为错误状态码（4xx/5xx）本身不具备重定向语义，错误信息放在响应体是符合规范的，和成功场景的302跳转逻辑不冲突。

更优的临时URL获取/下载方案 #

完全不需要通过抓取cURL verbose输出、正则匹配的方式提取URL，有更稳定简单的实现方式：

• 一步完成下载：给cURL添加-L参数开启自动跟随重定向，不需要手动处理跳转逻辑，直接就能把工件下载到本地，示例代码：

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token <TOKEN>" \
  -o artifact.zip \
  https://api.github.com/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip

• 单独提取临时URL：如果需要把临时URL传给其他工具使用，可以用cURL的-w（write-out）参数直接读取重定向地址，不需要解析stderr，稳定性远高于正则匹配：

# 提取临时URL存入变量，响应体直接丢弃
TEMP_URL=$(curl -s -o /dev/null -w "%{redirect_url}" \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token <TOKEN>" \
  https://api.github.com/repos/OWNER/REPO/actions/artifacts/ARTIFACT_ID/zip)

• 如果不需要手动调用API，直接使用GitHub CLI的gh artifact download命令即可自动完成鉴权、下载、解压全流程。

archive_format参数保留的原因 #

该参数是典型的API向前兼容设计，不存在冗余：

• 目前公有云GitHub仅支持zip格式的工件归档，不代表后续不会新增支持其他格式（比如tar.gz、7z等），保留路径参数后，后续新增格式支持不需要修改API路径结构、不需要升级API大版本，老用户的现有调用逻辑完全不受影响。
• 该参数可以显式声明客户端期望接收的归档格式，服务端可以做格式校验，客户端拿到响应后也不需要额外通过文件头猜测格式，方便后续解压等处理逻辑适配。
• 对于GitHub Enterprise Server等私有化部署场景，不同版本可能支持不同的归档格式，统一的带参数路径可以保持公有云、私有化部署的API结构一致，降低多版本维护成本。

内容的提问来源于stack exchange，提问作者Mathew