appbuilder-cicd-pipeline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

App Builder CI/CD Pipeline

App Builder CI/CD 流水线

Set up CI/CD pipelines for Adobe App Builder projects — GitHub Actions (primary), Azure DevOps, GitLab CI. Uses OAuth S2S credentials with IMS authentication. Repository secrets only (no environment secrets).

为Adobe App Builder项目搭建CI/CD流水线——以GitHub Actions为主，同时支持Azure DevOps、GitLab CI。采用带IMS认证的OAuth S2S凭证。仅使用仓库密钥（不支持环境密钥）。

Pattern Quick-Reference

模式速查表

User wants	Template
GitHub Actions deploy-to-stage	assets/deploy-stage.yml
GitHub Actions deploy-to-prod	assets/deploy-prod.yml
GitHub Actions PR tests	assets/pr-test.yml
Extract secrets from workspace	assets/fetch-secrets.sh
Azure DevOps / GitLab CI / Jenkins	references/generic-pipeline-guide.md
Secrets setup guide	references/secrets-management.md
Debugging deploy failures	references/debugging.md

用户需求	模板
GitHub Actions 部署至预发布环境	assets/deploy-stage.yml
GitHub Actions 部署至生产环境	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

Fast Path (for clear requests)

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

When the user says "set up CI/CD for my App Builder project" and they use GitHub, generate all 3 workflow files + secrets guide immediately:

Copy

assets/deploy-stage.yml

→

.github/workflows/deploy_stage.yml

Copy

assets/deploy-prod.yml

→

.github/workflows/deploy_prod.yml

Copy

assets/pr-test.yml

→

.github/workflows/pr_test.yml

Guide secrets setup using
```
references/secrets-management.md
```

If user specifies Azure DevOps, GitLab CI, or Jenkins → use

references/generic-pipeline-guide.md

当用户说“为我的App Builder项目搭建CI/CD”且使用GitHub时，立即生成全部3个工作流文件+密钥指南：

复制

assets/deploy-stage.yml

→

.github/workflows/deploy_stage.yml

复制

assets/deploy-prod.yml

→

.github/workflows/deploy_prod.yml

复制

assets/pr-test.yml

→

.github/workflows/pr_test.yml

参考
```
references/secrets-management.md
```
指导密钥设置

如果用户指定Azure DevOps、GitLab CI或Jenkins → 使用

references/generic-pipeline-guide.md

。

Quick Reference

速查信息

Workflow location:
```
.github/workflows/
```
at repository root
Bootstrap command:
```
aio app add ci
```
generates starter workflow files

Official actions:

adobe/aio-cli-setup-action@3

(CLI install) +

adobe/aio-apps-action@3.3.0

(build/test/deploy)

Auth model: OAuth Server-to-Server (S2S) with IMS — the
```
auth
```
command in
```
aio-apps-action
```
is DEPRECATED (JWT). Do not use it.
Secrets scope: Repository secrets only. App Builder does NOT support GitHub environment secrets.
Secrets per workspace: 14 secrets with workspace suffix (
```
_STAGE
```
,
```
_PROD
```
)
Prerequisite: Add "I/O Management API" to each workspace in Developer Console before extracting secrets
Workspace config: Run
```
aio app use <workspace.json>
```
to configure
```
.aio
```
and
```
.env
```
files

工作流位置： 仓库根目录下的
```
.github/workflows/
```
初始化命令：
```
aio app add ci
```
生成初始工作流文件
官方Action：
```
adobe/aio-cli-setup-action@3
```
（CLI安装） +
```
adobe/aio-apps-action@3.3.0
```
（构建/测试/部署）
认证模型： 带IMS的OAuth Server-to-Server（S2S）——
```
aio-apps-action
```
中的
```
auth
```
命令已废弃（JWT），请勿使用。
密钥范围： 仅仓库密钥。App Builder不支持GitHub环境密钥。
每个工作区的密钥： 14个带工作区后缀的密钥（
```
_STAGE
```
,
```
_PROD
```
）
前置条件： 在提取密钥前，需在开发者控制台的每个工作区中添加“I/O Management API”
工作区配置： 运行
```
aio app use <workspace.json>
```
配置
```
.aio
```
和
```
.env
```
文件

Full Workflow (for ambiguous or complex requests)

完整工作流（适用于模糊或复杂需求）

Check existing setup: Look for
```
.github/workflows/
```
(from
```
aio app add ci
```
or manual). Check if workflows already exist.
Determine CI/CD platform: GitHub Actions is default. Ask if user needs Azure DevOps, GitLab CI, or Jenkins.
Generate workflow files: Copy templates from
```
assets/
```
to
```
.github/workflows/
```
. Customize triggers, branch names, and environment suffixes as needed.
**Guide secrets setup:**a. Ensure "I/O Management API" is added to the workspace in Developer Consoleb. Download
```
workspace.json
```
from Developer Consolec. Run
```
aio app use <workspace.json>
```
to configure local
```
.aio
```
and
```
.env
```
d. Run
```
assets/fetch-secrets.sh
```
to extract credential valuese. Guide user to add each secret to GitHub repository secrets (NOT environment secrets)f. Add
```
_STAGE
```
or
```
_PROD
```
suffix to each secret name
Add custom secrets: If the app uses custom env vars, add them under the
```
env
```
key in the Deploy step
Validate: Run through
```
references/checklist.md
```
before merge
Troubleshoot: If deploy fails, consult
```
references/debugging.md
```
for common scenarios
Test: Push to a branch and verify workflow runs successfully

检查现有配置： 查找
```
.github/workflows/
```
（来自
```
aio app add ci
```
或手动配置），确认工作流是否已存在。
确定CI/CD平台： 默认使用GitHub Actions。询问用户是否需要Azure DevOps、GitLab CI或Jenkins。
生成工作流文件： 从
```
assets/
```
复制模板至
```
.github/workflows/
```
。根据需要自定义触发器、分支名称和环境后缀。
指导密钥设置：a. 确保开发者控制台的工作区中已添加“I/O Management API”b. 从开发者控制台下载
workspace.json
c. 运行
aio app use <workspace.json>
配置本地
.aio
和
.env
文件d. 运行
assets/fetch-secrets.sh
提取凭证值e. 指导用户将每个密钥添加至GitHub仓库密钥（而非环境密钥）f. 为每个密钥名称添加
```
_STAGE
```
或
```
_PROD
```
后缀
添加自定义密钥： 如果应用使用自定义环境变量，在部署步骤的
```
env
```
键下添加这些变量
验证： 合并前参考
```
references/checklist.md
```
进行检查
故障排除： 如果部署失败，参考
```
references/debugging.md
```
中的常见场景
测试： 推送至分支并验证工作流运行成功

Inputs To Request

需要询问的信息

Current repository path and CI/CD platform preference
Target Adobe organization, project, and workspace names
Whether Stage, Production, or both workspaces need CI/CD
Any custom secrets the application requires

当前仓库路径和CI/CD平台偏好
目标Adobe组织、项目和工作区名称
是否需要为预发布、生产或两者都配置CI/CD
应用所需的任何自定义密钥

Deliverables

交付成果

Workflow YAML files in
```
.github/workflows/
```
Secrets extraction output for repository configuration
Pre-merge validation against
```
references/checklist.md
```

```
.github/workflows/
```
中的工作流YAML文件
用于仓库配置的密钥提取输出
基于
```
references/checklist.md
```
的合并前CI就绪验证

Quality Bar

质量标准

All workflow YAML must be syntactically valid
Secrets must use repository scope, never environment scope
OAuth S2S credentials only — no JWT auth references
Each workspace gets its own secret set with correct suffix
Workflows must use pinned action versions (
```
@3
```
,
```
@3.3.0
```
)

所有工作流YAML必须语法有效
密钥必须使用仓库范围，绝不能使用环境范围
仅使用OAuth S2S凭证——禁止引用JWT认证
每个工作区拥有独立的密钥集，且后缀正确
工作流必须使用固定版本的Action（
```
@3
```
,
```
@3.3.0
```
）

References

参考资料

Use
```
references/github-actions-guide.md
```
for GitHub Actions workflow patterns and secrets table.
Use
```
references/generic-pipeline-guide.md
```
for Azure DevOps, GitLab CI, and Jenkins patterns.
Use
```
references/secrets-management.md
```
for OAuth S2S credential extraction and GitHub secrets setup.
Use
```
references/debugging.md
```
for troubleshooting deploy failures, CI errors, and workspace promotion issues.
Use
```
references/checklist.md
```
for pre-merge CI readiness validation.

Use

assets/deploy-stage.yml

assets/deploy-prod.yml

assets/pr-test.yml

as workflow templates.

Use
```
assets/fetch-secrets.sh
```
to extract secret values from workspace configuration.
Official Adobe docs: https://developer.adobe.com/app-builder/docs/guides/app_builder_guides/deployment/cicd-using-github-actions

GitHub Actions工作流模式和密钥表格参考
```
references/github-actions-guide.md
```
。
Azure DevOps、GitLab CI和Jenkins模式参考
```
references/generic-pipeline-guide.md
```
。
OAuth S2S凭证提取和GitHub密钥设置参考
```
references/secrets-management.md
```
。
部署失败、CI错误和工作区升级问题的故障排除参考
```
references/debugging.md
```
。
合并前CI就绪验证参考
```
references/checklist.md
```
。

工作流模板使用

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

Common Issues

常见问题

Workflow not triggering: Verify workflow files are committed to the default branch and triggers match your branching strategy.
Deploy fails with auth error: The
```
auth
```
command is deprecated. Ensure you are using OAuth S2S credentials, not JWT. Verify all 14 secrets are set correctly with the right workspace suffix.
"I/O Management API not found": Add the I/O Management API service to the workspace in Developer Console before extracting secrets.
Environment secrets not working: App Builder does NOT support GitHub environment secrets. Move all secrets to repository-level secrets.
Missing secrets: Run
```
fetch-secrets.sh
```
and compare output against the 14-secret table in
```
references/github-actions-guide.md
```
. Each value must be present and correctly suffixed.
Custom env vars not available in action: Add custom secrets under the
```
env
```
key in the Deploy step of the workflow, not just in GitHub secrets.

工作流未触发： 验证工作流文件已提交至默认分支，且触发器与你的分支策略匹配。
部署因认证错误失败：
```
auth
```
命令已废弃。确保使用OAuth S2S凭证而非JWT。验证所有14个密钥是否正确设置，并带有正确的工作区后缀。
“未找到I/O Management API”： 在提取密钥前，需在开发者控制台的工作区中添加I/O Management API服务。
环境密钥无法工作： App Builder不支持GitHub环境密钥。将所有密钥移至仓库级密钥。
密钥缺失： 运行
```
fetch-secrets.sh
```
并将输出与
```
references/github-actions-guide.md
```
中的14个密钥表格对比。每个值必须存在且后缀正确。
自定义环境变量在Action中不可用： 在工作流的部署步骤
```
env
```
键下添加自定义密钥，而不仅仅是在GitHub密钥中设置。

Chaining

链式关联

Chains FROM
```
appbuilder-action-scaffolder
```
(after actions are implemented)
Chains FROM
```
appbuilder-testing
```
(automated test execution in CI)
Standalone after setup (workflows run automatically on push/PR/release)

关联自
```
appbuilder-action-scaffolder
```
（Action实现完成后）
关联自
```
appbuilder-testing
```
（CI中的自动化测试执行）
设置完成后可独立运行（工作流在推送/PR/发布时自动执行）