App Builder CI/CD Pipeline

Pattern Quick-Reference

Fast Path (for clear requests)

1. Copy

   assets/deploy-stage.yml

   →

   .github/workflows/deploy_stage.yml

2. Copy

   assets/deploy-prod.yml

   →

   .github/workflows/deploy_prod.yml

3. Copy

   assets/pr-test.yml

   →

   .github/workflows/pr_test.yml

4. Guide secrets setup using

   references/secrets-management.md

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

Full Workflow (for ambiguous or complex requests)

1. Check existing setup: Look for

   .github/workflows/

   (from

   aio app add ci

   or manual). Check if workflows already exist.
2. Determine CI/CD platform: GitHub Actions is default. Ask if user needs Azure DevOps, GitLab CI, or Jenkins.
3. Generate workflow files: Copy templates from

   assets/

   to

   .github/workflows/

   . Customize triggers, branch names, and environment suffixes as needed.
4. **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
5. Add custom secrets: If the app uses custom env vars, add them under the

   env

   key in the Deploy step
6. Validate: Run through

   references/checklist.md

   before merge
7. Troubleshoot: If deploy fails, consult

   references/debugging.md

   for common scenarios
8. Test: Push to a branch and verify workflow runs successfully

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

Deliverables

• Workflow YAML files in

  .github/workflows/

• Secrets extraction output for repository configuration
• Pre-merge validation against

  references/checklist.md

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

  )

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

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.

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)