fix(autopilot): harden Repo2 deployment configuration and execution

README.md

@@ -241,7 +241,10 @@ import { defineCICD, Repository, EngineType } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
   engine: EngineType.CDK_PIPELINES, // omit for the default CODEPIPELINE
   stages: ['dev', 'prod'],
 });

docs/content/developer_guides/configuration.md

@@ -10,7 +10,10 @@ import { defineCICD, Repository } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
   stages: ['dev', { name: 'prod', env: { account: '111111111111', region: 'eu-west-1' } }],
 });
 ```
@@ -26,7 +29,7 @@ export default defineCICD({
 | `stages`                  | `Array<string \| StageInput>` | — (required)                           | Deployment stages, in order. See [Stages](#stages).                         |
 | `engine`                  | `EngineType`                  | `CODEPIPELINE`                         | Which engine renders the pipeline. See [Engine](#engine).                   |
 | `githubActions`           | `GitHubActionsConfig`         | —                                      | GitHub Actions engine config; read only when `engine` is `GITHUB_ACTIONS`.  |
-| `synthesizer`             | `{ type: SynthesizerType }`   | `DEFAULT`                              | Which stack synthesizer to install.                                         |
+| `synthesizer`             | `{ type: SynthesizerType, appId?: string }` | `DEFAULT`                   | Stack synthesizer. `appId` defaults to `application` for `APP_STAGING`.      |
 | `ci`                      | `CiConfigInput`               | engine defaults                        | Build steps and which stages CI synthesizes. See [CI](#ci).                 |
 | `deployModel`             | `DeployModel`                 | `ASSEMBLY_PROMOTION`                   | How the deployed assembly is produced. See [Deploy model](#deploy-model).   |
 | `codeArtifact`            | `CodeArtifactConfig`          | —                                      | Private CodeArtifact npm repo the builds authenticate against.              |
@@ -44,6 +47,10 @@ export default defineCICD({
 | `deployerImage`           | `BuildImage`                  | —                                      | Container mode: build & push a deployer image instead of deploying.         |
 | `plugins`                 | `PluginRef[]`                 | the default-on hardening set           | Security plugins (hardening Aspects) applied tree-wide. See [Security plugins](#security-plugins). |
 
+`APP_STAGING` is supported by the default flat `CODEPIPELINE` engine. The pinned alpha module does
+not support CDK Pipelines, so `CDK_PIPELINES` and `GITHUB_ACTIONS` reject that combination at synth
+time instead of silently producing an unusable self-mutating pipeline.
+
 ## `application` and `qualifier`
 
 `application` names the app and drives asset naming. `qualifier` is the CDK bootstrap qualifier; when
@@ -86,17 +93,20 @@ The source repository, constructed through a `Repository` factory. The tracked b
 `main`.
 
 ```typescript
-Repository.github('my-org/my-app'); // via a CodeStar (CodeConnections) connection
+Repository.codestarConnection('my-org/my-app', connArn); // GitHub or another provider via an existing connection ARN
 Repository.codecommit('my-repo'); // AWS CodeCommit
-Repository.codestarConnection('my-org/my-app', connArn); // any provider via an existing connection ARN
 Repository.s3('my-bucket/my-key'); // a versioned S3 object
-// each factory takes an optional trailing `branch` argument, e.g. Repository.github('my-org/my-app', 'develop')
+Repository.github('my-org/my-app'); // GitHub Actions engine only
+// each factory takes an optional trailing `branch` argument
+Repository.codestarConnection('my-org/my-app', connArn, 'develop');
 // CodeCommit is CREATED by default; pass { existing: true } to import an existing repo instead:
 Repository.codecommit('my-repo', 'main', { existing: true });
 ```
 
-When `engine` is `GITHUB_ACTIONS`, `repository` must be `Repository.github(...)` — the workflow runs
-where GitHub already checked the source out.
+The default `CODEPIPELINE` and `CDK_PIPELINES` engines require
+`Repository.codestarConnection(...)` for GitHub sources. When `engine` is `GITHUB_ACTIONS`,
+`repository` must instead be `Repository.github(...)` because the workflow runs where GitHub already
+checked the source out.
 
 ## Stages
 
@@ -308,7 +318,10 @@ Set a pipeline-level default with `deployRoleExternalId`, and override per stage
 ```typescript
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
   deployRoleExternalId: 'org-wide-external-id', // pipeline-level default
   stages: [
     {
@@ -325,7 +338,9 @@ export default defineCICD({
 
 Either value may be a literal, or a `resolve:secretsmanager:<arn>` reference resolved at exec time from
 the secret's `SecretString` (so the ExternalId can live in Secrets Manager rather than in
-`cicd.config.ts`).
+`cicd.config.ts`). The generated roles grant `secretsmanager:GetSecretValue`; use the Secrets Manager
+AWS-managed encryption key. A customer-managed KMS key additionally needs `kms:Decrypt`, which this
+configuration does not currently accept.
 
 ## Security plugins
 

docs/content/developer_guides/container_mode.md

@@ -28,7 +28,11 @@ import { defineCICD, Repository, BuildImage, ImageTagStrategy } from '@cdklabs/c
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
+  stages: ['dev'], // required by defineCICD; deployerImage mode creates no deploy actions
   deployerImage: BuildImage.docker({
     dockerfile: 'Dockerfile', // default; the image payload is your app + deps, NOT cdk.out
     // repositoryName: 'my-app-deployer', // reference an existing ECR repo; omit to provision one
@@ -37,6 +41,9 @@ export default defineCICD({
 });
 ```
 
+`stages` remains required by the `defineCICD` API, but `deployerImage` mode does not render deployment
+actions for those stages.
+
 `cdk-cicd deploy-ci` provisions the CI pipeline. Its single build project:
 
 1. runs `npm ci` and `cdk-cicd check` (CI as a validation gate),
@@ -63,6 +70,10 @@ image** to run and **where** to deploy it, via `defineDeployment` in a `deploy.c
 import { defineDeployment, Repository } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineDeployment({
+  // Repeat the deployer image's application/qualifier so Repo 2 can scope bootstrap-role IAM.
+  application: 'my-app',
+  qualifier: 'myapp',
+
   // The BASE deployer image repository (no tag). The per-stage version is appended at deploy time.
   image: '111111111111.dkr.ecr.eu-west-1.amazonaws.com/my-app-deployer',
 
@@ -84,6 +95,10 @@ export default defineDeployment({
 });
 ```
 
+`application`, `qualifier`, and `synthesizer` must match the image's `cicd.config` when it uses a
+custom bootstrap qualifier or `APP_STAGING`; Repo 2 needs that identity to grant the correct
+bootstrap and app-scoped asset roles.
+
 Each stage's **version lives in its own config file** in the CD repository (a hash or semver) — _not_
 baked in the image:
 

docs/content/workshops/autopilot-pipeline/01-config-driven-pipeline.md

@@ -31,7 +31,7 @@ import { defineCICD, Repository } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.codecommit('my-app'),   // or .github('org/my-app', 'main') / .s3('bucket/app.zip')
+  repository: Repository.codecommit('my-app'), // or .s3('bucket/app.zip')
   stages: ['dev', 'prod'],
 });
 ```
@@ -77,13 +77,13 @@ only ever write the few you need, because the wrapper resolves sensible defaults
 |---|---|---|
 | `application` | Logical name for the app and its resources. Defaults from `package.json#name`. | The prefix on pipeline and support-stack names — set it once so resources are recognizable. |
 | `qualifier` | Short (≤10 char) sanitized id used to disambiguate shared resources. Derived from `application`. | Only set it if two apps would otherwise collide on shared names. |
-| `repository` | The pipeline's source: `Repository.github('org/repo', branch?)`, `Repository.codecommit('name', branch?)`, or `Repository.s3('bucket/key', branch?)`. | This is *where* the pipeline reads code and *what* triggers it — the one field you almost always set explicitly. |
+| `repository` | The pipeline's source: `Repository.codestarConnection('org/repo', connectionArn, branch?)` for GitHub with the AWS-hosted engines, `Repository.codecommit(...)`, or `Repository.s3(...)`. `Repository.github(...)` is reserved for `GITHUB_ACTIONS`. | This is *where* the pipeline reads code and *what* triggers it — the one field you almost always set explicitly. |
 | `stages` | Ordered list of deployment stages — bare names or objects with `env`, `manualApproval`, `deployment`. | Your promotion path (dev → prod). Config-as-data, not pipeline code. Covered in the next chapter. |
 | `ci` | Customizes the CI phase: `steps`, `synthStages`, `image`. | Add your own build/test steps or a custom image. See [Customizing CI](#customizing-ci) below. |
 | `codeArtifact` | Authenticates builds to a private CodeArtifact repo (`domain`, `repository`, `account?`, `region?`, `npmScope?`). | Needed when your deps (or the wrapper itself, pre-release) live in a private registry. See chapter 4. |
 | `deployModel` | `DeployModel.ASSEMBLY_PROMOTION` (default) or `DeployModel.DEPLOY_TIME_SYNTH`. | Controls when synth happens — one synth per run vs per-stage at deploy time. See chapter 3. |
 | `asyncDeploy` | `boolean` (default `false`). Hands the CloudFormation wait to a Lambda instead of holding a build. | Saves build compute when the CloudFormation wait dominates. See chapter 3. |
-| `synthesizer` | `{ type?: SynthesizerType.DEFAULT \| SynthesizerType.APP_STAGING }`. | `DEFAULT` (`DefaultStackSynthesizer`) suits most apps; opt into `APP_STAGING` for per-app staging + roles-only bootstrap. |
+| `synthesizer` | `{ type?: SynthesizerType.DEFAULT \| SynthesizerType.APP_STAGING, appId?: string }`. | `DEFAULT` suits most apps. `APP_STAGING` uses `appId` (default: `application`) and currently works only with the default flat `CODEPIPELINE` engine. |
 | `engine` | Selects the CD engine (`EngineType`). | `EngineType.CODEPIPELINE` is the default and covers most cases — you rarely set it. Two alternates exist: `CDK_PIPELINES` (plain CDK Pipelines, no CodePipeline-specific extras) and `GITHUB_ACTIONS` (renders a `.github/workflows/deploy.yml` instead of an AWS-hosted pipeline — see [GitHub as source & CD engine](../../developer_guides/vcs_github.md)). Tuning for the default engine lives on the stages and `ci` (chapter 3), not here. |
 | `githubActions` | GitHub Actions engine config (`roleName`, `subjectClaims`, `workflowTriggers`, etc.). | Only read when `engine` is `EngineType.GITHUB_ACTIONS`. |
 | `deployerImage` | Turns the pipeline into a config-agnostic image builder (`BuildImage.docker({...})`). | The container-mode entry point. See chapter 5. |
@@ -107,7 +107,10 @@ import { defineCICD, Repository } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
   stages: ['dev', 'prod'],
   ci: {
     steps: {

docs/content/workshops/autopilot-pipeline/05-container-mode.md

@@ -22,7 +22,11 @@ import { defineCICD, Repository, BuildImage } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineCICD({
   application: 'my-app',
-  repository: Repository.github('my-org/my-app'),
+  repository: Repository.codestarConnection(
+    'my-org/my-app',
+    'arn:aws:codestar-connections:eu-west-1:111111111111:connection/01234567-89ab-cdef-0123-456789abcdef',
+  ),
+  stages: ['dev'], // required by defineCICD; deployerImage mode creates no deploy actions
   deployerImage: BuildImage.docker({
     dockerfile: 'Dockerfile', // default; the image payload is your app + deps, NOT cdk.out
     // repositoryName: 'my-app-deployer',   // reference an existing ECR repo; omit to provision one
@@ -31,6 +35,9 @@ export default defineCICD({
 });
 ```
 
+`stages` remains required by the `defineCICD` API, but `deployerImage` mode does not render deployment
+actions for those stages.
+
 ### What the Repo 1 pipeline does
 
 `cdk-cicd deploy-ci` provisions a **secondary CodePipeline** whose single build project:
@@ -61,6 +68,10 @@ Repo 2 is a small, app-agnostic **config repo** (no CDK code) that says **which
 import { defineDeployment, Repository } from '@cdklabs/cdk-cicd-wrapper';
 
 export default defineDeployment({
+  // Match the application/qualifier baked into the deployer image.
+  application: 'my-app',
+  qualifier: 'myapp',
+
   // The BASE deployer image repo (no tag). The per-stage version is appended at deploy time.
   image: '111111111111.dkr.ecr.eu-west-1.amazonaws.com/my-app-deployer',