appbuilder-cicd-pipeline

Files (11)

• SKILL.md
• deploy-prod.yml · assets/
• deploy-stage.yml · assets/
• fetch-secrets.sh · assets/
• pr-test.yml · assets/
• evals.json · evals/
• checklist.md · references/
• debugging.md · references/
• generic-pipeline-guide.md · references/
• github-actions-guide.md · references/
• secrets-management.md · references/

SKILL.md (first lines)

# App Builder CI/CD Pipeline

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).

## 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 |

## 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:

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`

If user specifies Azure DevOps, GitLab CI, or Jenkins → use `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:** one repository secret per credential, suffixed `_STAGE` / `_PROD`. Count them from `assets/fetch-secrets.sh` / the generated workflow — do not assume a fixed "14".
- **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 Console
   b. Download `workspace.json` from Developer Console
   c. Run `aio app use <workspace.json>` to configure local `.aio` and `.env`
   d. Run `assets/fetch-secrets.sh` to extract credential values
   e. 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](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 required secrets (do not assume a fixed count — see above) 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 secrets 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)

From CatCorner22/Cursor_Skills, Apache-2.0.

More from CatCorner22/Cursor_Skills