Jupyter项目GitHub Actions工作流升级指南：从upload-artifact v3迁移到v4

背景与问题概述

在持续集成/持续部署(CI/CD)流程中，GitHub Actions的upload-artifact动作扮演着重要角色，它允许工作流运行期间生成的构建产物（如测试报告、二进制文件等）被保存和共享。Jupyter项目作为知名的开源交互式计算环境，其CI流程也重度依赖这一功能。

2024年4月，GitHub官方宣布将逐步弃用upload-artifact的v3版本，并在2025年1月30日正式停止支持。这一变更影响了Jupyter项目的CI工作流，导致部分构建任务失败，表现为artifact上传步骤无法正常执行。

技术影响分析

upload-artifact从v3升级到v4并非简单的版本号变更，而是涉及以下技术层面的改进：

1. 性能优化：v4版本采用了新的压缩算法，显著提升了大型artifact的上传速度
2. 存储效率：改进的存储机制减少了重复文件的存储开销
3. API变更：部分参数名称和返回值结构发生了变化
4. 安全增强：增加了更严格的权限控制和校验机制

对于Jupyter项目而言，这些变更主要影响：

• 自动化测试报告的收集
• 构建产物的存档
• 跨工作流间的文件共享

升级实施要点

1. 语法变更适配

v3版本的典型用法：

- uses: actions/upload-artifact@v3
  with:
    name: test-results
    path: test-reports/

升级到v4后，基础语法保持兼容，但推荐使用更明确的新语法：

- uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: test-reports/
    retention-days: 5  # 新增参数，控制artifact保留天数

2. 路径处理改进

v4对路径处理逻辑进行了优化：

• 支持更复杂的glob模式匹配
• 路径解析更加严格，建议使用绝对路径
• 新增if-no-files-found参数，可配置当没有匹配文件时的行为（warn/error/ignore）

3. 跨工作流共享

v4改进了artifact的共享机制：

• 下载artifact时不再需要额外的权限配置
• 支持更细粒度的访问控制
• 共享artifact的元数据更加丰富

最佳实践建议

针对Jupyter项目的特性，建议采用以下升级策略：

1. 分阶段升级：先在非关键分支测试，再应用到主分支
2. 增加监控：对artifact上传步骤添加更详细的日志输出
3. 清理策略：合理设置retention-days参数，避免存储空间浪费
4. 错误处理：利用if-no-files-found参数优雅处理空artifact情况

回滚方案

虽然v4版本经过充分测试，但仍建议准备回滚方案：

1. 保留v3版本的工作流文件备份
2. 在关键步骤添加版本检查逻辑
3. 准备快速回滚的脚本或工作流

总结