Designs and debugs CI/CD, environments and release flow for AEM as a Cloud Service with Cloud Manager — pipeline types and quality gates, Git provider setup and its limitations, Maven build rules and package structure, environment variables and secrets, repoinit and index deployment, config pipelines for CDN and log forwarding, RDEs and the local SDK, logs, releases and rollback.
When agents use itUse this whenever the user sets up or debugs a Cloud Manager pipeline; hits a failed build, code-scanning or deploy step such as "Customer Package Quality" or a coverage threshold; asks about full-stack vs front-end vs web-tier vs config pipelines, dev/stage/prod or Rapid Development Environments, `aio aem:rde:install`, the AEM or dispatcher SDK, `.cloudmanager/java-version`, the `all` package, filter.xml, run modes, `$[env:]` and `$[secret:]` values, repoinit scripts, custom Oak indexes, cdn.yaml, branch strategy, or rollback. Also use it when planning a go-live checklist.
Install
Copilot (VS Code, Visual Studio, Copilot CLI and github.com) reads skills from the repository — commit them so the whole team gets them.
npx skills add AGCO-Global/org-skills --skill aem-cloud-manager -a github-copilot
# or with the org installer (adds .github/skills/aem-cloud-manager):
npx -y github:AGCO-Global/org-skills add skill aem-cloud-manager
Uses the open skills CLI. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, OpenCode, Windsurf and 60+ others — it asks which agent to install into.
Installs the aem-devops-skills plugin, which bundles all AEM / DevOps skills and keeps them updated.
/plugin marketplace add AGCO-Global/org-skills
/plugin install aem-devops-skills@org-skills
# or just this skill, in this repository:
npx skills add AGCO-Global/org-skills --skill aem-cloud-manager -a claude-code
Use Download .zip above, then upload it under Customize → Skills → Upload skill. Team and Enterprise admins can sync this repo as a plugin marketplace instead.
Installs into .agents/skills/, which Codex reads.
npx skills add AGCO-Global/org-skills --skill aem-cloud-manager -a codex
Installs into Cursor's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-cloud-manager -a cursor
Installs into Gemini CLI's skills folder.
npx skills add AGCO-Global/org-skills --skill aem-cloud-manager -a gemini-cli
Nothing to install. Press Download .zip above, unzip it, and drop the aem-cloud-manager folder into your tool's skills folder — .claude/skills/, .github/skills/, .cursor/skills/ or .agents/skills/. Step-by-step, per tool: How to use it. For any other tool with rules or custom prompts, Copy SKILL.md and paste it in — it is plain Markdown.
The npx commands need Node.js 20+ and use your normal git sign-in to GitHub, so they work while the repository is private. Without Node.js, see the No Node.js tab — a skill is a folder of Markdown, so copying it in works just as well.
Cloud Manager is the only road to stage and production: it builds from Git, gates on quality rules, deploys blue-green, and never rolls back content. Design every change so it passes the gates on the first run, is reproducible from a commit you can name, and is safe to deploy twice.
YAML from a config/ folder: kind values CDN, MaintenanceTasks, LogForwarding, API
Edge rules, purge keys, log forwarding — no code build
Code quality only
Nothing
PR and feature-branch validation
The production pipeline deploys to stage, runs the stage tests, waits for approval, then deploys to production. Gate levels, the failures you will actually hit (mixed packages, /libs overlays, index definitions, coverage), the build-environment facts and the UI-test opt-in are in references/quality-gates.md.
3. Git
Cloud Manager builds from an Adobe-managed repository, or from your own: GitHub.com (via the Adobe GitHub app), GitHub Enterprise Server, GitLab, Bitbucket Cloud and Azure DevOps (personal access token plus a webhook). Private repositories buy you PR-level quality checks and no mirroring drift, at the cost of three things worth designing around:
No Git tag is created for production full-stack pipeline runs — tag the release yourself in CI, or you cannot name what is in production.
On-commit triggers do not start pipelines automatically — trigger them from your own CI or start them manually.
No artifact reuse between pipelines.
Protect the branch Cloud Manager builds: pull-request review, a green local mvn clean install, and a green code-quality pipeline before merge.
feature/* → PR → code-quality pipeline (+ an RDE for the demo)
develop → dev pipeline (manual or CI-triggered on a private repo)
release/x → stage via the production pipeline, UAT, fix forward
main → production pipeline, approval, scheduled deploy; tag the commit yourself
hotfix/* → from the release commit, merged back to main and develop
4. Maven build and packages
Modules: core, ui.apps, ui.apps.structure, ui.config, ui.content, ui.frontend, dispatcher, all, it.tests, ui.tests. Only all is deployed, and anything it does not embed is not deployed — the most common "my config never applied" cause.
Package types: application for /apps and /oak:index, content for /conf, /content, /home, container for all. mixed fails the gates.
filter.xml: narrow roots, and mode="merge" for anything authors own. A bare <filter root="/content/acme"/> deletes authored content on every deploy.
Layout details and merge modes: repository-layout.md in ../../architecture/aem-architecture/references/.
5. Configuration, secrets and repoinit
Run modes are fixed: author, publish, dev, stage, prod, rde and their combinations. There are no custom run modes; use environment variables for per-environment values.
Create the variables in Cloud Manager per environment (and per service where it matters) before the deploy that needs them. Changing one restarts services on that environment, so batch changes and keep them off peak hours.
repoinit ships in org.apache.sling.jcr.repoinit.RepositoryInitializer~acme.cfg.json:
create service user acme-price-sync with forced path system/cq:services/acme
set principal ACL for acme-price-sync
allow jcr:read on /content/acme
end
create path (sling:Folder) /conf/acme/settings
with forced path system/cq:services/<project> plus set principal ACL is the Cloud Service form — principal-based authorization is the default under that path. Map the user with ServiceUserMapperImpl.amended~acme.cfg.json.
Custom Oak indexes ship in ui.apps under /oak:index and follow one naming rule: oak-index-naming.md in ../../development/aem-backend-development/references/. Deploy an index change ahead of the code that needs it — reindexing lengthens the deployment on large repositories.
6. A config-pipeline change end to end
Rotating the CDN purge key touches no Java and needs no build: create a secret environment variable (CDN_PURGEKEY_021225), reference it from config/cdn.yaml as a purge authenticator (purgeKey1 / purgeKey2 — two slots exist so you rotate without downtime), run the config pipeline, and drop the old key in a second run once the new one works. The YAML is in cdn-config.md in ../../architecture/aem-dispatcher/references/.
7. Logs, releases and rollback
Download or tail logs from Cloud Manager (aio cloudmanager:environment:tail-log), or forward them with a LogForwarding config. Log at INFO in production; DEBUG on dev and RDE only. Adobe applies AEM maintenance updates automatically and blocks your pipeline while one runs, so keep the build green against the latest SDK — a failing custom functional test blocks the product update.
Rollback is a redeploy. A failed deploy leaves the previous version serving; reverting a successful one means deploying the previous commit. Content changed by packages or by authors is not reverted, so every content migration must be forward-only and idempotent.
Deliverable format
## Pipeline design
Repo: <Adobe-managed | provider> Java: 21 Modules: <list>
| Pipeline | Type | Branch | Trigger | Target | Gate overrides |
Env vars / secrets: <name → purpose, scope, secret?>
Run-mode config folders: <list>
## Release checklist — the go-live list from references/quality-gates.md, filled in
Checklist
The right pipeline type for the change, and dispatcher ownership is unambiguous
all embeds every module that must deploy
No mixed packages; author-owned filter roots use mode="merge"
.cloudmanager/java-version is 21 (or a justified 17)
Secrets are $[secret:] env vars; build credentials are pipeline variables
Service users come from repoinit with forced path system/cq:services/… and set principal ACL
Index definitions are correctly named and shipped before dependent code
On a private repository, the release commit is tagged by your own CI
Gate overrides, if any, are dated, owned and not security findings
Content migrations are idempotent and forward-only
Anti-patterns
A mixed package (/apps plus /content) → split into ui.apps and ui.content.
Service users shipped as a content package → repoinit.
Editing an existing index definition in place → deploy the next -custom-<n> version.
Secrets in .cfg.json or a committed settings.xml → $[secret:] env vars and pipeline variables.
Overriding an Important gate to hit a date → fix it, or record a dated exception with an owner; never override security or compatibility findings.
Assuming "on commit" works on a private repository → trigger from your CI; no tag is created either.
Treating RDE or dev as the source of truth → everything goes through Git and a pipeline.
Expecting a redeploy to undo content changes → it does not; plan migrations forward-only.
A local SDK several releases behind the cloud → align aem-sdk-api and the SDK jar with the current release.
Go deeper
references/quality-gates.md — gate levels, pipeline steps, the failures you actually hit and their fixes, build environment, UI-test opt-in and REPORTS_PATH.
references/local-and-rde.md — AEM and dispatcher SDKs, the full RDE command surface and limits, hibernation, aio cloudmanager and Advanced Networking lead time.
repository-layout.md in ../../architecture/aem-architecture/references/ and oak-index-naming.md in ../../development/aem-backend-development/references/.
Sibling skills: aem-dispatcher for the config it deploys, aem-testing for the tests the gates run, aem-cloud-migration for getting onto the platform, aem-security for secrets and access.
---
name: aem-cloud-manager
description: >
Designs and debugs CI/CD, environments and release flow for AEM as a Cloud Service with Cloud Manager — pipeline types and quality gates, Git provider setup and its limitations, Maven build rules and package structure, environment variables and secrets, repoinit and index deployment, config pipelines for CDN and log forwarding, RDEs and the local SDK, logs, releases and rollback. Use this whenever the user sets up or debugs a Cloud Manager pipeline; hits a failed build, code-scanning or deploy step such as "Customer Package Quality" or a coverage threshold; asks about full-stack vs front-end vs web-tier vs config pipelines, dev/stage/prod or Rapid Development Environments, `aio aem:rde:install`, the AEM or dispatcher SDK, `.cloudmanager/java-version`, the `all` package, filter.xml, run modes, `$[env:]` and `$[secret:]` values, repoinit scripts, custom Oak indexes, cdn.yaml, branch strategy, or rollback. Also use it when planning a go-live checklist.
metadata:
technology: AEM
type: devops
---
# AEM Cloud Manager CI/CD
> **Targets:** AEM as a Cloud Service 2026.x, Cloud Manager (Java 21 builds, SonarQube 9.9) · **Verified:** 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/using-cloud-manager/cicd-pipelines/introduction-ci-cd-pipelines
Cloud Manager is the only road to stage and production: it builds from Git, gates on quality rules, deploys blue-green, and never rolls back content. Design every change so it passes the gates on the first run, is reproducible from a commit you can name, and is safe to deploy twice.
## 1. Decide first
| Question | Default | Change when |
|---|---|---|
| Pipeline for a code change | **Full-stack** | Dispatcher-only change → web-tier config pipeline; theme-only → front-end pipeline; CDN/log/maintenance YAML → config pipeline |
| Dispatcher config owner | Full-stack pipeline | A web-tier pipeline exists → the full-stack pipeline stops deploying dispatcher config for that environment |
| Git hosting | Adobe-managed repository | Your own provider, with the three limitations in §3 accepted |
| Where a value lives | `$[env:NAME]` / `$[secret:NAME]` resolved at runtime | Build-time credentials (private Maven repo, npm token) → **pipeline variables** |
| Java build version | `21` in `.cloudmanager/java-version` | `17` for a dependency that needs it; `11` only for legacy; `8` is unsupported |
| Service users and ACLs | repoinit in an OSGi factory config | Never a content package |
| Fast iteration | RDE (`aio aem:rde:install`) | Sign-off, performance and integration testing → dev or stage |
| Overriding an "Important" gate | No | A dated, recorded exception with an owner — never for security or Cloud Service compatibility |
| Reverting a bad deploy | Redeploy the previous commit | There is no rollback button, and **content is never reverted** |
## 2. Pipelines and gates
| Pipeline | Deploys | Use for |
|---|---|---|
| **Full-stack** | `all` package (code + content packages) and, unless a web-tier pipeline exists, dispatcher config | Every Java, HTL or OSGi change |
| **Front-end** | The `dist` output of a Node module, as static theme files | Sites whose theme ships on its own cadence (`aem-frontend-development`) |
| **Web-tier config** | Dispatcher configuration only | Frequent dispatcher changes; requires flexible mode |
| **Config** | YAML from a `config/` folder: `kind` values `CDN`, `MaintenanceTasks`, `LogForwarding`, `API` | Edge rules, purge keys, log forwarding — no code build |
| **Code quality only** | Nothing | PR and feature-branch validation |
The production pipeline deploys to stage, runs the stage tests, waits for approval, then deploys to production. Gate levels, the failures you will actually hit (mixed packages, `/libs` overlays, index definitions, coverage), the build-environment facts and the UI-test opt-in are in `references/quality-gates.md`.
## 3. Git
Cloud Manager builds from an Adobe-managed repository, or from your own: **GitHub.com** (via the Adobe GitHub app), **GitHub Enterprise Server**, **GitLab**, **Bitbucket Cloud** and **Azure DevOps** (personal access token plus a webhook). Private repositories buy you PR-level quality checks and no mirroring drift, at the cost of three things worth designing around:
- **No Git tag is created** for production full-stack pipeline runs — tag the release yourself in CI, or you cannot name what is in production.
- **On-commit triggers do not start pipelines automatically** — trigger them from your own CI or start them manually.
- **No artifact reuse** between pipelines.
Protect the branch Cloud Manager builds: pull-request review, a green local `mvn clean install`, and a green code-quality pipeline before merge.
```
feature/* → PR → code-quality pipeline (+ an RDE for the demo)
develop → dev pipeline (manual or CI-triggered on a private repo)
release/x → stage via the production pipeline, UAT, fix forward
main → production pipeline, approval, scheduled deploy; tag the commit yourself
hotfix/* → from the release commit, merged back to main and develop
```
## 4. Maven build and packages
- Modules: `core`, `ui.apps`, `ui.apps.structure`, `ui.config`, `ui.content`, `ui.frontend`, `dispatcher`, `all`, `it.tests`, `ui.tests`. Only `all` is deployed, and **anything it does not embed is not deployed** — the most common "my config never applied" cause.
- Package types: `application` for `/apps` and `/oak:index`, `content` for `/conf`, `/content`, `/home`, `container` for `all`. `mixed` fails the gates.
- `filter.xml`: narrow roots, and `mode="merge"` for anything authors own. A bare `<filter root="/content/acme"/>` deletes authored content on every deploy.
- Layout details and merge modes: `repository-layout.md` in `../../architecture/aem-architecture/references/`.
## 5. Configuration, secrets and repoinit
- Run modes are fixed: `author`, `publish`, `dev`, `stage`, `prod`, `rde` and their combinations. There are no custom run modes; use environment variables for per-environment values.
```json
{ "apiEndpoint": "$[env:PARTNER_API_URL;default=https://sandbox.example.com]",
"apiKey": "$[secret:PARTNER_API_KEY]" }
```
- Create the variables in Cloud Manager per environment (and per service where it matters) **before** the deploy that needs them. Changing one restarts services on that environment, so batch changes and keep them off peak hours.
- repoinit ships in `org.apache.sling.jcr.repoinit.RepositoryInitializer~acme.cfg.json`:
```
create service user acme-price-sync with forced path system/cq:services/acme
set principal ACL for acme-price-sync
allow jcr:read on /content/acme
end
create path (sling:Folder) /conf/acme/settings
```
`with forced path system/cq:services/<project>` plus `set principal ACL` is the Cloud Service form — principal-based authorization is the default under that path. Map the user with `ServiceUserMapperImpl.amended~acme.cfg.json`.
- Custom Oak indexes ship in `ui.apps` under `/oak:index` and follow one naming rule: `oak-index-naming.md` in `../../development/aem-backend-development/references/`. Deploy an index change ahead of the code that needs it — reindexing lengthens the deployment on large repositories.
## 6. A config-pipeline change end to end
Rotating the CDN purge key touches no Java and needs no build: create a **secret** environment variable (`CDN_PURGEKEY_021225`), reference it from `config/cdn.yaml` as a `purge` authenticator (`purgeKey1` / `purgeKey2` — two slots exist so you rotate without downtime), run the config pipeline, and drop the old key in a second run once the new one works. The YAML is in `cdn-config.md` in `../../architecture/aem-dispatcher/references/`.
## 7. Logs, releases and rollback
- Download or tail logs from Cloud Manager (`aio cloudmanager:environment:tail-log`), or forward them with a `LogForwarding` config. Log at `INFO` in production; `DEBUG` on dev and RDE only. Adobe applies AEM maintenance updates automatically and blocks your pipeline while one runs, so keep the build green against the latest SDK — a failing custom functional test blocks the product update.
- **Rollback is a redeploy.** A failed deploy leaves the previous version serving; reverting a successful one means deploying the previous commit. Content changed by packages or by authors is not reverted, so every content migration must be forward-only and idempotent.
## Deliverable format
```
## Pipeline design
Repo: <Adobe-managed | provider> Java: 21 Modules: <list>
| Pipeline | Type | Branch | Trigger | Target | Gate overrides |
Env vars / secrets: <name → purpose, scope, secret?>
Run-mode config folders: <list>
## Release checklist — the go-live list from references/quality-gates.md, filled in
```
## Checklist
- [ ] The right pipeline type for the change, and dispatcher ownership is unambiguous
- [ ] `all` embeds every module that must deploy
- [ ] No mixed packages; author-owned filter roots use `mode="merge"`
- [ ] `.cloudmanager/java-version` is `21` (or a justified `17`)
- [ ] Secrets are `$[secret:]` env vars; build credentials are pipeline variables
- [ ] Service users come from repoinit with `forced path system/cq:services/…` and `set principal ACL`
- [ ] Index definitions are correctly named and shipped before dependent code
- [ ] On a private repository, the release commit is tagged by your own CI
- [ ] Gate overrides, if any, are dated, owned and not security findings
- [ ] Content migrations are idempotent and forward-only
## Anti-patterns
- **A mixed package** (`/apps` plus `/content`) → split into `ui.apps` and `ui.content`.
- **Service users shipped as a content package** → repoinit.
- **Editing an existing index definition in place** → deploy the next `-custom-<n>` version.
- **Secrets in `.cfg.json` or a committed `settings.xml`** → `$[secret:]` env vars and pipeline variables.
- **Overriding an Important gate to hit a date** → fix it, or record a dated exception with an owner; never override security or compatibility findings.
- **Assuming "on commit" works on a private repository** → trigger from your CI; no tag is created either.
- **Treating RDE or dev as the source of truth** → everything goes through Git and a pipeline.
- **Expecting a redeploy to undo content changes** → it does not; plan migrations forward-only.
- **A local SDK several releases behind the cloud** → align `aem-sdk-api` and the SDK jar with the current release.
## Go deeper
- `references/quality-gates.md` — gate levels, pipeline steps, the failures you actually hit and their fixes, build environment, UI-test opt-in and `REPORTS_PATH`.
- `references/local-and-rde.md` — AEM and dispatcher SDKs, the full RDE command surface and limits, hibernation, `aio cloudmanager` and Advanced Networking lead time.
- `repository-layout.md` in `../../architecture/aem-architecture/references/` and `oak-index-naming.md` in `../../development/aem-backend-development/references/`.
- Sibling skills: `aem-dispatcher` for the config it deploys, `aem-testing` for the tests the gates run, `aem-cloud-migration` for getting onto the platform, `aem-security` for secrets and access.