Projen项目GitHub Actions构建失败问题分析与解决方案

背景概述

近期，许多使用projen管理的项目在GitHub Actions的构建和发布工作流中出现了失败情况，错误信息显示为"Unknown command"。这一问题源于GitHub Actions团队对actions/upload-artifact动作的一次变更。

问题根源

GitHub Actions在2024年8月19日宣布了一项变更，默认情况下actions/upload-artifact将不再上传隐藏文件，因为这些文件可能包含敏感信息。这一变更在2024年9月2日作为次要版本更新发布。由于projen没有将GitHub官方动作锁定到特定版本，任何依赖隐藏文件上传的工作流都开始失败。

技术细节

问题的核心在于projen的默认配置中，升级工作流依赖于一个名为.repo.patch的隐藏文件。当GitHub Actions停止上传隐藏文件后，升级工作流无法完成，导致构建过程失败。

解决方案

临时解决方案

对于需要立即修复的项目，可以手动将upload-artifact动作版本设置为兼容版本：

project.github.actions.set("actions/upload-artifact", "actions/upload-artifact@v4.3.6");

此方案需要projen版本至少为v0.67.56。

永久解决方案

升级到projen v0.87.0或更高版本，该版本已完全兼容actions/upload-artifacts的新行为。可以通过以下方式升级：

1. 运行npx projen upgrade并合并建议的更改
2. 手动将projen版本约束改为^0.87.4，然后运行包安装并合并更改

批量处理方案

对于管理多个仓库的用户，可以使用以下bash脚本进行批量升级：

#!/usr/bin/env bash

REPO=$1
UPGRADE=${2:-upgrade}
WORKING_DIR=$(mktemp -d -t upgrade-projen)

cd $WORKING_DIR;
echo $WORKING_DIR
gh repo clone $1 .
git switch --create automation-local/fix-upgrade
npx --yes projen install:ci
npx projen $UPGRADE
git add .
git commit -m "chore(deps): upgrade projen dependencies"
git --no-pager show --summary
git push -u origin HEAD
gh pr create --title "chore(deps): upgrade projen dependencies" --body "Automated PR to upgrade projen dependencies"

技术启示

这一事件凸显了依赖管理中的几个重要问题：

1. 版本锁定策略：对于关键依赖，特别是构建工具链中的组件，应考虑锁定版本以避免意外变更
2. 隐藏文件依赖：构建系统应避免依赖隐藏文件，这些文件可能在不同环境下有特殊处理
3. 自动化升级机制：需要设计更健壮的升级机制，即使在部分功能失效时也能完成关键更新

总结

projen团队已发布v0.87.0及更高版本，完全解决了与GitHub Actions上传隐藏文件变更的兼容性问题。虽然完全自动化的修复路径仍然受限，但通过手动干预或脚本辅助，用户可以顺利完成升级。这一事件也促使社区重新思考构建工具对第三方服务的依赖管理策略。