appbuilder-cicd-pipeline

App Builder CI/CD 流水线

为 Adobe App Builder 项目设置 CI/CD 流水线：GitHub Actions（首选）、Azure DevOps、GitLab CI。使用 OAuth S2S 凭据进行 IMS 身份验证。仅使用仓库机密（不使用环境机密）。

模式快速参考

用户需求	模板
GitHub Actions 部署到 Stage	assets/deploy-stage.yml
GitHub Actions 部署到 Prod	assets/deploy-prod.yml
GitHub Actions PR 测试	assets/pr-test.yml
从工作区提取机密	assets/fetch-secrets.sh
Azure DevOps / GitLab CI / Jenkins	references/generic-pipeline-guide.md
机密设置指南	references/secrets-management.md
调试部署失败	references/debugging.md

快速路径（适用于明确的请求）

当用户表示“为我的 App Builder 项目设置 CI/CD”，且使用 GitHub 时，立即生成全部 3 个工作流文件和机密指南：

1. 复制 assets/deploy-stage.yml → .github/workflows/deploy_stage.yml
2. 复制 assets/deploy-prod.yml → .github/workflows/deploy_prod.yml
3. 复制 assets/pr-test.yml → .github/workflows/pr_test.yml
4. 使用 references/secrets-management.md 指导设置机密

如果用户指定 Azure DevOps、GitLab CI 或 Jenkins → 使用 references/generic-pipeline-guide.md。

快速参考

• 工作流位置： 仓库根目录下的 .github/workflows/
• 引导命令： aio app add ci 可生成工作流文件初始模板
• 官方操作： adobe/aio-cli-setup-action@3（安装 CLI）+ adobe/[email protected]（构建/测试/部署）
• 身份验证模式： 使用 IMS 的 OAuth Server-to-Server（S2S）——aio-apps-action 中的 auth 命令已弃用（JWT）。请勿使用。
• 机密范围： 仅限仓库机密。App Builder 不支持 GitHub 环境机密。
• 每个工作区的机密： 14 个机密，使用工作区后缀（_STAGE、_PROD）
• 前提条件： 提取机密之前，先在 Developer Console 的每个工作区中添加“I/O Management API”
• 工作区配置： 运行 aio app use <workspace.json> 来配置 .aio 和 .env 文件

完整工作流（适用于含糊或复杂的请求）

1. 检查现有设置： 查找 .github/workflows/（由 aio app add ci 生成或手动创建）。检查工作流是否已存在。
2. 确定 CI/CD 平台： 默认使用 GitHub Actions。询问用户是否需要 Azure DevOps、GitLab CI 或 Jenkins。
3. 生成工作流文件： 将 assets/ 中的模板复制到 .github/workflows/。根据需要自定义触发条件、分支名称和环境后缀。
4. **指导设置机密：**a. 确保已在 Developer Console 的工作区中添加“I/O Management API”b. 从 Developer Console 下载 workspace.jsonc. 运行 aio app use <workspace.json> 配置本地 .aio 和 .envd. 运行 assets/fetch-secrets.sh 提取凭据值e. 指导用户将每个机密添加到 GitHub 仓库机密中（而非环境机密）f. 为每个机密名称添加 _STAGE 或 _PROD 后缀
5. 添加自定义机密： 如果应用使用自定义环境变量，请将其添加到 Deploy 步骤下的 env 键中
6. 验证： 合并前按照 references/checklist.md 逐项检查
7. 排查问题： 如果部署失败，请查阅 references/debugging.md 了解常见情况
8. 测试： 推送到分支，并确认工作流成功运行

需要收集的信息

• 当前仓库路径和 CI/CD 平台偏好
• 目标 Adobe 组织、项目和工作区名称
• 需要为 Stage、Production 还是两个工作区设置 CI/CD
• 应用所需的任何自定义机密

交付内容

• .github/workflows/ 中的工作流 YAML 文件
• 用于配置仓库的机密提取结果
• 合并前依据 references/checklist.md 进行验证

质量标准

• 所有工作流 YAML 都必须语法有效
• 密钥必须使用仓库范围，绝不能使用环境范围
• 仅使用 OAuth S2S 凭据，不得引用 JWT 身份验证
• 每个工作区都必须有自己的一组密钥，并使用正确的后缀
• 工作流必须使用固定版本的操作（@3、@3.3.0）

参考资料

• 使用 references/github-actions-guide.md 了解 GitHub Actions 工作流模式和密钥表。
• 使用 references/generic-pipeline-guide.md 了解 Azure DevOps、GitLab CI 和 Jenkins 模式。
• 使用 references/secrets-management.md 了解 OAuth S2S 凭据提取和 GitHub 密钥设置。
• 使用 references/debugging.md 排查部署失败、CI 错误和工作区提升问题。
• 使用 references/checklist.md 验证合并前的 CI 就绪情况。
• 使用 assets/deploy-stage.yml、assets/deploy-prod.yml、assets/pr-test.yml 作为工作流模板。
• 使用 assets/fetch-secrets.sh 从工作区配置中提取密钥值。
• Adobe 官方文档：https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/deployment/cicd-using-github-actions

常见问题

• 工作流未触发： 确认工作流文件已提交到默认分支，并且触发条件符合你的分支策略。
• 部署因身份验证错误而失败： auth 命令已弃用。请确保使用 OAuth S2S 凭据，而非 JWT。确认全部 14 个密钥均已正确设置，并带有正确的工作区后缀。
• “I/O Management API not found”： 在提取密钥之前，先将 I/O Management API 服务添加到 Developer Console 中的工作区。
• 环境密钥不起作用： App Builder 不支持 GitHub 环境密钥。请将所有密钥移至仓库级密钥。
• 缺少密钥： 运行 fetch-secrets.sh，并将输出与 references/github-actions-guide.md 中的 14 个密钥表进行比较。每个值都必须存在，且带有正确的后缀。
• 操作中无法使用自定义环境变量： 在工作流 Deploy 步骤的 env 键下添加自定义密钥，而不只是将它们添加到 GitHub 密钥中。

链接关系

• 链接自 appbuilder-action-scaffolder（操作实现后）
• 链接自 appbuilder-testing（在 CI 中自动执行测试）
• 设置后可独立运行（工作流会在推送／PR／发布时自动运行）