@cdklabs/cdk-cicd-wrapper 2.3.1 → 2.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. package/.jsii +758 -196
  2. package/API.md +526 -45
  3. package/README.md +11 -0
  4. package/lib/app/DeploymentPipelineApp.js +7 -3
  5. package/lib/app/PipelineApp.js +12 -4
  6. package/lib/appconfig/accessor.js +1 -1
  7. package/lib/config/build-image.d.ts +17 -1
  8. package/lib/config/build-image.js +57 -3
  9. package/lib/config/default-synthesizer-role-arn.d.ts +38 -0
  10. package/lib/config/default-synthesizer-role-arn.js +63 -0
  11. package/lib/config/define.d.ts +50 -1
  12. package/lib/config/define.js +117 -6
  13. package/lib/config/naming.d.ts +7 -2
  14. package/lib/config/naming.js +9 -9
  15. package/lib/config/repository.js +1 -1
  16. package/lib/config/types.d.ts +123 -11
  17. package/lib/config/types.js +6 -2
  18. package/lib/engine/cdkpipelines/CdkPipelinesEngine.d.ts +6 -0
  19. package/lib/engine/cdkpipelines/CdkPipelinesEngine.js +419 -43
  20. package/lib/engine/codepipeline/CodePipelineEngine.d.ts +22 -15
  21. package/lib/engine/codepipeline/CodePipelineEngine.js +681 -127
  22. package/lib/engine/codepipeline/DeploymentPipeline.d.ts +8 -5
  23. package/lib/engine/codepipeline/DeploymentPipeline.js +937 -72
  24. package/lib/engine/external-id-secrets.d.ts +17 -0
  25. package/lib/engine/external-id-secrets.js +53 -0
  26. package/lib/engine/github/GitHubActionsEngine.d.ts +3 -4
  27. package/lib/engine/github/GitHubActionsEngine.js +446 -34
  28. package/lib/index.d.ts +3 -1
  29. package/lib/index.js +6 -2
  30. package/lib/runtime/attach.js +1 -1
  31. package/lib/runtime/inject.d.ts +41 -3
  32. package/lib/runtime/inject.js +259 -22
  33. package/lib/runtime/pipeline-assembler.d.ts +7 -1
  34. package/lib/runtime/pipeline-assembler.js +144 -36
  35. package/lib/runtime/register.js +10 -1
  36. package/lib/support/AccessLogsForBucketAspect.d.ts +14 -8
  37. package/lib/support/AccessLogsForBucketAspect.js +52 -37
  38. package/lib/support/DestroyEncryptionKeysOnDeleteAspect.js +1 -1
  39. package/lib/support/DisablePublicIPAssignmentForEC2Aspect.js +1 -1
  40. package/lib/support/EncryptBucketOnTransitAspect.js +1 -1
  41. package/lib/support/EncryptCloudWatchLogGroupsAspect.js +1 -1
  42. package/lib/support/EncryptSNSTopicOnTransitAspect.js +1 -1
  43. package/lib/support/LambdaDLQAspect.js +1 -1
  44. package/lib/support/LogRetentionAspect.js +1 -1
  45. package/lib/support/RotateEncryptionKeysAspect.js +1 -1
  46. package/lib/support/SupportResources.d.ts +24 -14
  47. package/lib/support/SupportResources.js +42 -24
  48. package/package.json +6 -5
package/API.md CHANGED
@@ -156,11 +156,15 @@ public readonly pipeline: CodePipeline;
156
156
 
157
157
  ### DeploymentPipeline <a name="DeploymentPipeline" id="@cdklabs/cdk-cicd-wrapper.DeploymentPipeline"></a>
158
158
 
159
- Renders the CD CodePipeline into `scope` (a Stack): Source (the config repo) -> a "Deploy" stage with one privileged-CodeBuild action per ungated target (parallel), then a "DeployGated" stage with the gated targets, each behind its own manual approval.
159
+ Renders the CD CodePipeline into `scope` (a Stack): Source (the config repo) followed by ordered deployment stages.
160
160
 
161
- Each action runs `cdk-cicd deploy --from-image --target
162
- <stage>` -- pulling that target's own image version, read from deploy.config at run time. The CLI is
163
- installed from the source repo's `package.json` (`npm ci`), so the config repo carries no CDK code.
161
+ Each contiguous run of ungated targets shares one stage and can deploy in parallel.
162
+ Each gated target has its own stage, with its approval at run order 1 and only that target's deploy
163
+ action(s) at run order 2, so the gate blocks every later target without reordering the declaration.
164
+ A sequential target uses one action for all regions; a parallel multi-region target fans out one action
165
+ per region. Each action runs `cdk-cicd deploy --from-image --target <stage>` -- pulling that target's own
166
+ image version, read from deploy.config at run time. The CLI is installed from the source repo's
167
+ `package.json` (`npm ci`), so the config repo carries no CDK code.
164
168
 
165
169
  #### Initializers <a name="Initializers" id="@cdklabs/cdk-cicd-wrapper.DeploymentPipeline.Initializer"></a>
166
170
 
@@ -642,10 +646,9 @@ Exposed so a test or an opt-in `bin/` can reach it.
642
646
  A GitHub Actions workflow rendered from an Autopilot config + a stage factory.
643
647
 
644
648
  Reproduces the Blueprint shape: a
645
- `GitHubActionRole` the workflow assumes over OIDC, a Synth job, and one job (with a GitHub Environment,
646
- so an environment protection rule set up on GitHub's side gates it) per deployment stage. Manual-approval
647
- config is NOT translated into a CDK step here -- as in Blueprint, GitHub Environments are the gate; every stage
648
- gets its own environment regardless of `manualApproval`, and gating is configured in the GitHub UI.
649
+ `GitHubActionRole` the workflow assumes over OIDC, a Synth job, and one job (with a GitHub Environment)
650
+ per deployment stage. GitHub owns the environment protection rules, so approval-gated stages are accepted
651
+ only when config explicitly acknowledges that required reviewers are configured on those environments.
649
652
 
650
653
  #### Initializers <a name="Initializers" id="@cdklabs/cdk-cicd-wrapper.GitHubActionsEngine.Initializer"></a>
651
654
 
@@ -1306,20 +1309,17 @@ The compliance/access-log destination bucket (Blueprint `ComplianceBucketProvide
1306
1309
  Created on first
1307
1310
  read, same as every other property here. Requires `complianceLogBucketName`: unlike
1308
1311
  `artifactBucket`, this bucket's name must be explicit and predictable so other buckets' logging
1309
- configuration (and, cross-region, Blueprint's name-substitution convention) can reference it.
1312
+ configuration can reference it by name.
1310
1313
 
1311
- Blueprint provisioned this bucket via a custom-resource Lambda so a redeploy could tolerate the bucket
1312
- already existing (`BucketAlreadyOwnedByYou`); Autopilot provisions it as a plain, CloudFormation-managed
1313
- `Bucket` instead -- simpler, and the "already exists" case Blueprint tolerated doesn't arise here since
1314
- this construct's stack owns the bucket for the life of the pipeline.
1314
+ By default Autopilot provisions a plain, CloudFormation-managed `Bucket`. For an in-place Blueprint
1315
+ migration, set `createComplianceLogBucket: false` to reference the existing bucket by name instead.
1316
+ CDK intentionally cannot mutate an imported bucket policy, so that mode leaves the bucket and policy
1317
+ entirely under their current owner's lifecycle.
1315
1318
 
1316
- Folds in the TLS/SSE policy fix Blueprint's Stage-1 change (`0b7ae02`) made and Autopilot must not regress:
1317
- enforcing encryption-in-transit works with a plain `Bool` condition on `aws:SecureTransport`
1318
- (`enforceSSL`, below) because that key is always present on every request. Enforcing encryption
1319
- *at rest* does not: `s3:x-amz-server-side-encryption` is only present in the request context when
1320
- the caller actually sets the header, so a `Bool` check against `"false"` never matches a request
1321
- that omits the header entirely -- exactly the unencrypted upload this statement exists to block.
1322
- The `Null` operator below checks for the header's *absence*, which a `Bool` check cannot.
1319
+ The bucket uses default SSE-S3 encryption. Writers, including the S3 server-access-log delivery
1320
+ service, do not need to send an `x-amz-server-side-encryption` header: S3 encrypts the object at
1321
+ rest after accepting it. A bucket-policy deny based on that header would block valid log delivery,
1322
+ so transport encryption is enforced here while at-rest encryption is enforced by bucket defaults.
1323
1323
 
1324
1324
  ---
1325
1325
 
@@ -1371,8 +1371,24 @@ const accessLogsForBucketAspectProps: AccessLogsForBucketAspectProps = { ... }
1371
1371
 
1372
1372
  | **Name** | **Type** | **Description** |
1373
1373
  | --- | --- | --- |
1374
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucketAccount">complianceLogBucketAccount</a></code> | <code>string</code> | AWS account that owns the compliance bucket. |
1374
1375
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | The name of the bucket every visited bucket's access logs are delivered to. |
1375
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.mainRegion">mainRegion</a></code> | <code>string</code> | The region the compliance log bucket lives in. |
1376
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucketRegion">complianceLogBucketRegion</a></code> | <code>string</code> | AWS Region containing the compliance bucket. |
1377
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucket">complianceLogBucket</a></code> | <code>aws-cdk-lib.aws_s3.IBucket</code> | The concrete destination bucket when it exists in the same CDK app. |
1378
+
1379
+ ---
1380
+
1381
+ ##### `complianceLogBucketAccount`<sup>Required</sup> <a name="complianceLogBucketAccount" id="@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucketAccount"></a>
1382
+
1383
+ ```typescript
1384
+ public readonly complianceLogBucketAccount: string;
1385
+ ```
1386
+
1387
+ - *Type:* string
1388
+
1389
+ AWS account that owns the compliance bucket.
1390
+
1391
+ S3 access-log delivery cannot cross accounts.
1376
1392
 
1377
1393
  ---
1378
1394
 
@@ -1388,19 +1404,32 @@ The name of the bucket every visited bucket's access logs are delivered to.
1388
1404
 
1389
1405
  ---
1390
1406
 
1391
- ##### `mainRegion`<sup>Required</sup> <a name="mainRegion" id="@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.mainRegion"></a>
1407
+ ##### `complianceLogBucketRegion`<sup>Required</sup> <a name="complianceLogBucketRegion" id="@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucketRegion"></a>
1392
1408
 
1393
1409
  ```typescript
1394
- public readonly mainRegion: string;
1410
+ public readonly complianceLogBucketRegion: string;
1395
1411
  ```
1396
1412
 
1397
1413
  - *Type:* string
1398
1414
 
1399
- The region the compliance log bucket lives in.
1415
+ AWS Region containing the compliance bucket.
1416
+
1417
+ S3 access-log delivery cannot cross Regions.
1418
+
1419
+ ---
1420
+
1421
+ ##### `complianceLogBucket`<sup>Optional</sup> <a name="complianceLogBucket" id="@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspectProps.property.complianceLogBucket"></a>
1422
+
1423
+ ```typescript
1424
+ public readonly complianceLogBucket: IBucket;
1425
+ ```
1426
+
1427
+ - *Type:* aws-cdk-lib.aws_s3.IBucket
1428
+
1429
+ The concrete destination bucket when it exists in the same CDK app.
1400
1430
 
1401
- When a visited bucket's stack is deployed to a
1402
- different region, `complianceLogBucketName` is rewritten by substituting `mainRegion` for that
1403
- stack's region -- same cross-region name convention as Blueprint.
1431
+ Supplying it lets same-stack
1432
+ source buckets depend explicitly on the destination bucket and its policy.
1404
1433
 
1405
1434
  ---
1406
1435
 
@@ -1784,6 +1813,7 @@ const ciConfig: CiConfig = { ... }
1784
1813
  | --- | --- | --- |
1785
1814
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CiConfig.property.steps">steps</a></code> | <code>{[ key: string ]: string}</code> | Named build steps as shell commands, e.g. `{ lint: 'npx cdk-cicd validate' }`. Empty means the engine applies its built-in default set. |
1786
1815
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CiConfig.property.synthStages">synthStages</a></code> | <code>string[]</code> | Which stages CI synthesizes. |
1816
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.CiConfig.property.codeBuildImageCredentials">codeBuildImageCredentials</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials">CodeBuildImageCredentials</a></code> | Secrets Manager credentials for an authenticated external-registry `image`. |
1787
1817
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CiConfig.property.image">image</a></code> | <code>string</code> | Optional CodeBuild image override. |
1788
1818
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CiConfig.property.partialBuildSpec">partialBuildSpec</a></code> | <code>aws-cdk-lib.aws_codebuild.BuildSpec</code> | Escape hatch (Blueprint `CDKPipelineProps.ciBuildSpec`, migrated): deep-merged into the CI build project's generated buildspec via `codebuild.mergeBuildSpecs`, augmenting rather than replacing the engine's own phases. Scoped the same way Blueprint scoped it -- the CI build project only, not self-update or per-stage deploy projects. |
1789
1819
 
@@ -1817,6 +1847,21 @@ explicitly; `defineCICD`'s `'all'` shorthand resolves to the full stage list her
1817
1847
 
1818
1848
  ---
1819
1849
 
1850
+ ##### `codeBuildImageCredentials`<sup>Optional</sup> <a name="codeBuildImageCredentials" id="@cdklabs/cdk-cicd-wrapper.CiConfig.property.codeBuildImageCredentials"></a>
1851
+
1852
+ ```typescript
1853
+ public readonly codeBuildImageCredentials: CodeBuildImageCredentials;
1854
+ ```
1855
+
1856
+ - *Type:* <a href="#@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials">CodeBuildImageCredentials</a>
1857
+
1858
+ Secrets Manager credentials for an authenticated external-registry `image`.
1859
+
1860
+ Supported by the CodeBuild engines only. Managed CodeBuild images and private ECR images use
1861
+ their own credential models and reject this setting.
1862
+
1863
+ ---
1864
+
1820
1865
  ##### `image`<sup>Optional</sup> <a name="image" id="@cdklabs/cdk-cicd-wrapper.CiConfig.property.image"></a>
1821
1866
 
1822
1867
  ```typescript
@@ -1934,6 +1979,51 @@ Defaults to the pipeline's own region.
1934
1979
 
1935
1980
  ---
1936
1981
 
1982
+ ### CodeBuildImageCredentials <a name="CodeBuildImageCredentials" id="@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials"></a>
1983
+
1984
+ Secrets Manager credentials used by CodeBuild to pull an authenticated external-registry image.
1985
+
1986
+ #### Initializer <a name="Initializer" id="@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials.Initializer"></a>
1987
+
1988
+ ```typescript
1989
+ import { CodeBuildImageCredentials } from '@cdklabs/cdk-cicd-wrapper'
1990
+
1991
+ const codeBuildImageCredentials: CodeBuildImageCredentials = { ... }
1992
+ ```
1993
+
1994
+ #### Properties <a name="Properties" id="Properties"></a>
1995
+
1996
+ | **Name** | **Type** | **Description** |
1997
+ | --- | --- | --- |
1998
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials.property.secretArn">secretArn</a></code> | <code>string</code> | Complete ARN of the Secrets Manager secret containing the registry username and password. |
1999
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials.property.encryptionKeyArn">encryptionKeyArn</a></code> | <code>string</code> | Customer-managed KMS key encrypting `secretArn`, when one is used. |
2000
+
2001
+ ---
2002
+
2003
+ ##### `secretArn`<sup>Required</sup> <a name="secretArn" id="@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials.property.secretArn"></a>
2004
+
2005
+ ```typescript
2006
+ public readonly secretArn: string;
2007
+ ```
2008
+
2009
+ - *Type:* string
2010
+
2011
+ Complete ARN of the Secrets Manager secret containing the registry username and password.
2012
+
2013
+ ---
2014
+
2015
+ ##### `encryptionKeyArn`<sup>Optional</sup> <a name="encryptionKeyArn" id="@cdklabs/cdk-cicd-wrapper.CodeBuildImageCredentials.property.encryptionKeyArn"></a>
2016
+
2017
+ ```typescript
2018
+ public readonly encryptionKeyArn: string;
2019
+ ```
2020
+
2021
+ - *Type:* string
2022
+
2023
+ Customer-managed KMS key encrypting `secretArn`, when one is used.
2024
+
2025
+ ---
2026
+
1937
2027
  ### CodeCommitSourceOptions <a name="CodeCommitSourceOptions" id="@cdklabs/cdk-cicd-wrapper.CodeCommitSourceOptions"></a>
1938
2028
 
1939
2029
  Options for a CodeCommit source.
@@ -1988,7 +2078,7 @@ const codePipelineEngineProps: CodePipelineEngineProps = { ... }
1988
2078
 
1989
2079
  | **Name** | **Type** | **Description** |
1990
2080
  | --- | --- | --- |
1991
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineEngineProps.property.buildImage">buildImage</a></code> | <code>string</code> | CodeBuild image for the CI and deploy projects. |
2081
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineEngineProps.property.buildImage">buildImage</a></code> | <code>string</code> | CodeBuild image for the CI Build project only. |
1992
2082
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineEngineProps.property.removalPolicy">removalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | Removal policy for the pipeline's own support resources (artifact bucket, encryption key). |
1993
2083
 
1994
2084
  ---
@@ -2001,9 +2091,10 @@ public readonly buildImage: string;
2001
2091
 
2002
2092
  - *Type:* string
2003
2093
 
2004
- CodeBuild image for the CI and deploy projects.
2094
+ CodeBuild image for the CI Build project only.
2005
2095
 
2006
- Defaults to the standard Amazon Linux image.
2096
+ Overrides `config.ci.image`; defaults to the
2097
+ standard Amazon Linux image.
2007
2098
 
2008
2099
  ---
2009
2100
 
@@ -2042,7 +2133,7 @@ const codePipelineRoleNames: CodePipelineRoleNames = { ... }
2042
2133
 
2043
2134
  | **Name** | **Type** | **Description** |
2044
2135
  | --- | --- | --- |
2045
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineRoleNames.property.buildRolePrefix">buildRolePrefix</a></code> | <code>string</code> | Prefix for the per-stage CodeBuild project roles: each stage's build role is named `<buildRolePrefix>-<stage>` (plus the CI/self-update projects, `<buildRolePrefix>-build` / `<buildRolePrefix>-selfupdate`). |
2136
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineRoleNames.property.buildRolePrefix">buildRolePrefix</a></code> | <code>string</code> | Prefix for every flat-engine CodeBuild project role. |
2046
2137
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineRoleNames.property.pipeline">pipeline</a></code> | <code>string</code> | `RoleName` forced on the CodePipeline pipeline role. |
2047
2138
 
2048
2139
  ---
@@ -2055,7 +2146,11 @@ public readonly buildRolePrefix: string;
2055
2146
 
2056
2147
  - *Type:* string
2057
2148
 
2058
- Prefix for the per-stage CodeBuild project roles: each stage's build role is named `<buildRolePrefix>-<stage>` (plus the CI/self-update projects, `<buildRolePrefix>-build` / `<buildRolePrefix>-selfupdate`).
2149
+ Prefix for every flat-engine CodeBuild project role.
2150
+
2151
+ The suffix is the lower-cased construct id
2152
+ with a trailing `Project` removed: `BuildProject` -> `build`, `UpdatePipeline` ->
2153
+ `updatepipeline`, and `Deploy-dev` -> `deploy-dev`.
2059
2154
 
2060
2155
  Omit to keep CDK-generated names.
2061
2156
 
@@ -2178,6 +2273,81 @@ Fields whose absence is reported as `MISSING_KEY`.
2178
2273
 
2179
2274
  ---
2180
2275
 
2276
+ ### DefaultSynthesizerRoleArnOptions <a name="DefaultSynthesizerRoleArnOptions" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions"></a>
2277
+
2278
+ Target values used to specialize a DefaultStackSynthesizer role ARN.
2279
+
2280
+ #### Initializer <a name="Initializer" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.Initializer"></a>
2281
+
2282
+ ```typescript
2283
+ import { DefaultSynthesizerRoleArnOptions } from '@cdklabs/cdk-cicd-wrapper'
2284
+
2285
+ const defaultSynthesizerRoleArnOptions: DefaultSynthesizerRoleArnOptions = { ... }
2286
+ ```
2287
+
2288
+ #### Properties <a name="Properties" id="Properties"></a>
2289
+
2290
+ | **Name** | **Type** | **Description** |
2291
+ | --- | --- | --- |
2292
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.account">account</a></code> | <code>string</code> | Concrete target AWS account. |
2293
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.region">region</a></code> | <code>string</code> | Concrete target AWS Region. |
2294
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.partition">partition</a></code> | <code>string</code> | Concrete target AWS partition. |
2295
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.qualifier">qualifier</a></code> | <code>string</code> | Bootstrap qualifier. |
2296
+
2297
+ ---
2298
+
2299
+ ##### `account`<sup>Required</sup> <a name="account" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.account"></a>
2300
+
2301
+ ```typescript
2302
+ public readonly account: string;
2303
+ ```
2304
+
2305
+ - *Type:* string
2306
+
2307
+ Concrete target AWS account.
2308
+
2309
+ ---
2310
+
2311
+ ##### `region`<sup>Required</sup> <a name="region" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.region"></a>
2312
+
2313
+ ```typescript
2314
+ public readonly region: string;
2315
+ ```
2316
+
2317
+ - *Type:* string
2318
+
2319
+ Concrete target AWS Region.
2320
+
2321
+ ---
2322
+
2323
+ ##### `partition`<sup>Optional</sup> <a name="partition" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.partition"></a>
2324
+
2325
+ ```typescript
2326
+ public readonly partition: string;
2327
+ ```
2328
+
2329
+ - *Type:* string
2330
+
2331
+ Concrete target AWS partition.
2332
+
2333
+ When omitted, `${AWS::Partition}` remains intact to match the role ARN emitted in a cloud assembly.
2334
+
2335
+ ---
2336
+
2337
+ ##### `qualifier`<sup>Optional</sup> <a name="qualifier" id="@cdklabs/cdk-cicd-wrapper.DefaultSynthesizerRoleArnOptions.property.qualifier"></a>
2338
+
2339
+ ```typescript
2340
+ public readonly qualifier: string;
2341
+ ```
2342
+
2343
+ - *Type:* string
2344
+
2345
+ Bootstrap qualifier.
2346
+
2347
+ Defaults to the CDK default qualifier (`hnb659fds`).
2348
+
2349
+ ---
2350
+
2181
2351
  ### DeploymentConfig <a name="DeploymentConfig" id="@cdklabs/cdk-cicd-wrapper.DeploymentConfig"></a>
2182
2352
 
2183
2353
  Forced deployer / CloudFormation-execution roles for a stage.
@@ -2195,7 +2365,7 @@ const deploymentConfig: DeploymentConfig = { ... }
2195
2365
  | **Name** | **Type** | **Description** |
2196
2366
  | --- | --- | --- |
2197
2367
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.DeploymentConfig.property.cfnExecutionRole">cfnExecutionRole</a></code> | <code>string</code> | ARN CloudFormation assumes to execute the change set. |
2198
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.DeploymentConfig.property.deployRole">deployRole</a></code> | <code>string</code> | ARN the CLI assumes to deploy (passed as `cdk deploy --role-arn`). |
2368
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.DeploymentConfig.property.deployRole">deployRole</a></code> | <code>string</code> | ARN CDK assumes for deployment operations. |
2199
2369
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.DeploymentConfig.property.externalId">externalId</a></code> | <code>string</code> | ExternalId presented when assuming `deployRole` (the `sts:ExternalId` a hardened cross-account trust policy requires). |
2200
2370
 
2201
2371
  ---
@@ -2220,7 +2390,10 @@ public readonly deployRole: string;
2220
2390
 
2221
2391
  - *Type:* string
2222
2392
 
2223
- ARN the CLI assumes to deploy (passed as `cdk deploy --role-arn`).
2393
+ ARN CDK assumes for deployment operations.
2394
+
2395
+ It is written to the cloud assembly as the stack's
2396
+ deployment-role assumption; it is not CloudFormation's execution `RoleARN`.
2224
2397
 
2225
2398
  ---
2226
2399
 
@@ -2237,7 +2410,9 @@ ExternalId presented when assuming `deployRole` (the `sts:ExternalId` a hardened
2237
2410
  Overrides the pipeline-level `ResolvedCicdConfig.deployRoleExternalId` for
2238
2411
  this stage. A literal, or a `resolve:secretsmanager:<arn>` reference resolved at synth time (the
2239
2412
  same `resolve:` convention `VpcConfig.vpcId` uses). Ignored when `deployRole` is unset -- an
2240
- ExternalId only applies to a role assumption the wrapper actually performs.
2413
+ ExternalId only applies to a role assumption the wrapper actually performs. A literal, or a
2414
+ `resolve:secretsmanager:<complete literal secret ARN>` reference resolved at synth time (the same
2415
+ `resolve:` convention `VpcConfig.vpcId` uses). Wildcards and non-ARN secret identifiers are rejected.
2241
2416
 
2242
2417
  ---
2243
2418
 
@@ -2513,6 +2688,8 @@ const gitHubActionsConfig: GitHubActionsConfig = { ... }
2513
2688
 
2514
2689
  | **Name** | **Type** | **Description** |
2515
2690
  | --- | --- | --- |
2691
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.buildContainerCredentials">buildContainerCredentials</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials">GitHubBuildContainerCredentials</a></code> | GitHub Actions secret names used as the Build-Synth container's registry credentials. |
2692
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.environmentProtectionConfigured">environmentProtectionConfigured</a></code> | <code>boolean</code> | Confirms that every generated GitHub Environment used by a stage with `manualApproval: true` has a required-reviewer protection rule configured in GitHub. |
2516
2693
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.openIdConnectProviderArn">openIdConnectProviderArn</a></code> | <code>string</code> | An existing GitHub OIDC provider's ARN. |
2517
2694
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.publishAssetsAuthRegion">publishAssetsAuthRegion</a></code> | <code>string</code> | Region the workflow assumes the OIDC role in when publishing assets (NOT the region assets publish to). |
2518
2695
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.roleName">roleName</a></code> | <code>string</code> | Name of the OIDC role the workflow assumes to deploy. |
@@ -2524,6 +2701,38 @@ const gitHubActionsConfig: GitHubActionsConfig = { ... }
2524
2701
 
2525
2702
  ---
2526
2703
 
2704
+ ##### `buildContainerCredentials`<sup>Optional</sup> <a name="buildContainerCredentials" id="@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.buildContainerCredentials"></a>
2705
+
2706
+ ```typescript
2707
+ public readonly buildContainerCredentials: GitHubBuildContainerCredentials;
2708
+ ```
2709
+
2710
+ - *Type:* <a href="#@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials">GitHubBuildContainerCredentials</a>
2711
+
2712
+ GitHub Actions secret names used as the Build-Synth container's registry credentials.
2713
+
2714
+ Only external-registry `ci.image` values support this setting. Values are rendered as
2715
+ `${{ secrets.NAME }}` expressions; literal credentials are never accepted.
2716
+
2717
+ ---
2718
+
2719
+ ##### `environmentProtectionConfigured`<sup>Optional</sup> <a name="environmentProtectionConfigured" id="@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.environmentProtectionConfigured"></a>
2720
+
2721
+ ```typescript
2722
+ public readonly environmentProtectionConfigured: boolean;
2723
+ ```
2724
+
2725
+ - *Type:* boolean
2726
+ - *Default:* false
2727
+
2728
+ Confirms that every generated GitHub Environment used by a stage with `manualApproval: true` has a required-reviewer protection rule configured in GitHub.
2729
+
2730
+ The workflow file can name an environment, but GitHub does not let CDK configure that
2731
+ environment's protection rules. The engine therefore fails closed for approval-gated stages
2732
+ unless this acknowledgement is explicitly set.
2733
+
2734
+ ---
2735
+
2527
2736
  ##### `openIdConnectProviderArn`<sup>Optional</sup> <a name="openIdConnectProviderArn" id="@cdklabs/cdk-cicd-wrapper.GitHubActionsConfig.property.openIdConnectProviderArn"></a>
2528
2737
 
2529
2738
  ```typescript
@@ -2545,7 +2754,7 @@ public readonly publishAssetsAuthRegion: string;
2545
2754
  ```
2546
2755
 
2547
2756
  - *Type:* string
2548
- - *Default:* "us-west-2"
2757
+ - *Default:* the concrete pipeline stack region
2549
2758
 
2550
2759
  Region the workflow assumes the OIDC role in when publishing assets (NOT the region assets publish to).
2551
2760
 
@@ -2691,6 +2900,51 @@ Falls back to `githubActions.workflowName` when set; otherwise `cdk-pipelines-gi
2691
2900
 
2692
2901
  ---
2693
2902
 
2903
+ ### GitHubBuildContainerCredentials <a name="GitHubBuildContainerCredentials" id="@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials"></a>
2904
+
2905
+ GitHub secret names used to authenticate the Build-Synth job container to an external registry.
2906
+
2907
+ #### Initializer <a name="Initializer" id="@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials.Initializer"></a>
2908
+
2909
+ ```typescript
2910
+ import { GitHubBuildContainerCredentials } from '@cdklabs/cdk-cicd-wrapper'
2911
+
2912
+ const gitHubBuildContainerCredentials: GitHubBuildContainerCredentials = { ... }
2913
+ ```
2914
+
2915
+ #### Properties <a name="Properties" id="Properties"></a>
2916
+
2917
+ | **Name** | **Type** | **Description** |
2918
+ | --- | --- | --- |
2919
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials.property.passwordSecretName">passwordSecretName</a></code> | <code>string</code> | GitHub Actions secret containing the registry password or access token. |
2920
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials.property.usernameSecretName">usernameSecretName</a></code> | <code>string</code> | GitHub Actions secret containing the registry username. |
2921
+
2922
+ ---
2923
+
2924
+ ##### `passwordSecretName`<sup>Required</sup> <a name="passwordSecretName" id="@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials.property.passwordSecretName"></a>
2925
+
2926
+ ```typescript
2927
+ public readonly passwordSecretName: string;
2928
+ ```
2929
+
2930
+ - *Type:* string
2931
+
2932
+ GitHub Actions secret containing the registry password or access token.
2933
+
2934
+ ---
2935
+
2936
+ ##### `usernameSecretName`<sup>Required</sup> <a name="usernameSecretName" id="@cdklabs/cdk-cicd-wrapper.GitHubBuildContainerCredentials.property.usernameSecretName"></a>
2937
+
2938
+ ```typescript
2939
+ public readonly usernameSecretName: string;
2940
+ ```
2941
+
2942
+ - *Type:* string
2943
+
2944
+ GitHub Actions secret containing the registry username.
2945
+
2946
+ ---
2947
+
2694
2948
  ### LambdaDLQAspectProps <a name="LambdaDLQAspectProps" id="@cdklabs/cdk-cicd-wrapper.LambdaDLQAspectProps"></a>
2695
2949
 
2696
2950
  Constructor props for {@link LambdaDLQAspect}.
@@ -2902,8 +3156,9 @@ is configured (no NAT egress; the CodeBuild VPC endpoints below cover AWS API ca
2902
3156
  A generic private npm registry the pipeline's builds authenticate against with a bearer token (Blueprint `NPMRegistryConfig`, migrated).
2903
3157
 
2904
3158
  Unlike `CodeArtifactConfig` (an `aws codeartifact login`), this covers
2905
- any npm-compatible registry: when set, every build project writes a `.npmrc` -- scoped to `scope` when
2906
- given, otherwise overriding the default registry -- with an auth token read from Secrets Manager.
3159
+ any npm-compatible registry: jobs that install packages use a temporary npm config outside the source
3160
+ checkout -- scoped to `scope` when given, otherwise overriding the default registry -- with an auth
3161
+ token read from Secrets Manager.
2907
3162
 
2908
3163
  #### Initializer <a name="Initializer" id="@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.Initializer"></a>
2909
3164
 
@@ -2919,6 +3174,7 @@ const npmRegistryConfig: NpmRegistryConfig = { ... }
2919
3174
  | --- | --- | --- |
2920
3175
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.basicAuthSecretArn">basicAuthSecretArn</a></code> | <code>string</code> | ARN of the Secrets Manager secret holding the bearer token (the secret's plain `SecretString`). |
2921
3176
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.url">url</a></code> | <code>string</code> | The registry URL, e.g. `https://npm.example.com/`. |
3177
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.encryptionKeyArn">encryptionKeyArn</a></code> | <code>string</code> | Customer-managed KMS key encrypting `basicAuthSecretArn`, when one is used. |
2922
3178
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.scope">scope</a></code> | <code>string</code> | npm scope to bind to the registry, e.g. `cdklabs` for `@cdklabs/*`. Omit to override the default registry. |
2923
3179
 
2924
3180
  ---
@@ -2947,6 +3203,18 @@ The registry URL, e.g. `https://npm.example.com/`.
2947
3203
 
2948
3204
  ---
2949
3205
 
3206
+ ##### `encryptionKeyArn`<sup>Optional</sup> <a name="encryptionKeyArn" id="@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.encryptionKeyArn"></a>
3207
+
3208
+ ```typescript
3209
+ public readonly encryptionKeyArn: string;
3210
+ ```
3211
+
3212
+ - *Type:* string
3213
+
3214
+ Customer-managed KMS key encrypting `basicAuthSecretArn`, when one is used.
3215
+
3216
+ ---
3217
+
2950
3218
  ##### `scope`<sup>Optional</sup> <a name="scope" id="@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig.property.scope"></a>
2951
3219
 
2952
3220
  ```typescript
@@ -3140,6 +3408,7 @@ const proxyConfig: ProxyConfig = { ... }
3140
3408
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ProxyConfig.property.noProxy">noProxy</a></code> | <code>string[]</code> | Hosts that bypass the proxy. |
3141
3409
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ProxyConfig.property.proxySecretArn">proxySecretArn</a></code> | <code>string</code> | ARN of the Secrets Manager secret holding the proxy credentials, as the keys `username`, `password`, `http_proxy_port`, `https_proxy_port` and `proxy_domain`. |
3142
3410
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ProxyConfig.property.proxyTestUrl">proxyTestUrl</a></code> | <code>string</code> | URL curl'd (through the proxy) to confirm it works before the install phase's real commands run. |
3411
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ProxyConfig.property.encryptionKeyArn">encryptionKeyArn</a></code> | <code>string</code> | Customer-managed KMS key encrypting `proxySecretArn`, when one is used. |
3143
3412
 
3144
3413
  ---
3145
3414
 
@@ -3182,6 +3451,18 @@ URL curl'd (through the proxy) to confirm it works before the install phase's re
3182
3451
 
3183
3452
  ---
3184
3453
 
3454
+ ##### `encryptionKeyArn`<sup>Optional</sup> <a name="encryptionKeyArn" id="@cdklabs/cdk-cicd-wrapper.ProxyConfig.property.encryptionKeyArn"></a>
3455
+
3456
+ ```typescript
3457
+ public readonly encryptionKeyArn: string;
3458
+ ```
3459
+
3460
+ - *Type:* string
3461
+
3462
+ Customer-managed KMS key encrypting `proxySecretArn`, when one is used.
3463
+
3464
+ ---
3465
+
3185
3466
  ### RemovalPolicies <a name="RemovalPolicies" id="@cdklabs/cdk-cicd-wrapper.RemovalPolicies"></a>
3186
3467
 
3187
3468
  Retention of stateful resources.
@@ -3302,6 +3583,7 @@ const resolvedCicdConfig: ResolvedCicdConfig = { ... }
3302
3583
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.codeBuildEnvSettings">codeBuildEnvSettings</a></code> | <code>aws-cdk-lib.aws_codebuild.BuildEnvironment</code> | CodeBuild environment overrides -- privileged mode, compute type, environment variables -- applied to every CodeBuild project the pipeline creates (Blueprint `codeBuildEnvSettings`, migrated from `CodeBuildFactoryProvider`/`PipelineBlueprint.codeBuildEnvSettings(...)`). Reuses CDK's own `BuildEnvironment` rather than a bespoke type, so it stays a drop-in for Blueprint callers. `buildImage` here is a full `IBuildImage` (e.g. an ARM or GPU managed image); it is distinct from the engines' own `buildImage` constructor prop, which takes a Docker-registry image string -- that prop wins when both are set. |
3303
3584
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.codePipelineRoleNames">codePipelineRoleNames</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodePipelineRoleNames">CodePipelineRoleNames</a></code> | Forced IAM role names for the flat `CODEPIPELINE` engine's own roles. |
3304
3585
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | The name of the compliance/access-log destination bucket, if configured (Blueprint `ComplianceBucketProvider`/`ComplianceLogBucketStack`, migrated). |
3586
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.createComplianceLogBucket">createComplianceLogBucket</a></code> | <code>boolean</code> | Whether the pipeline stack creates and manages `complianceLogBucketName`. |
3305
3587
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.deployerImage">deployerImage</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.BuildImage">BuildImage</a></code> | Container mode (Repo 1): when set, the pipeline runs CI then builds & pushes a config-agnostic deployer image to ECR instead of deploying stages. |
3306
3588
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.deployRoleExternalId">deployRoleExternalId</a></code> | <code>string</code> | Pipeline-level default ExternalId presented when assuming a stage's forced `deployRole`. |
3307
3589
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.express">express</a></code> | <code>boolean</code> | Deploy with **CloudFormation express mode** (`cdk deploy --express`). |
@@ -3420,7 +3702,7 @@ public readonly application: string;
3420
3702
 
3421
3703
  Application name;
3422
3704
 
3423
- drives the bootstrap qualifier and asset naming.
3705
+ drives the derived bootstrap qualifier and asset naming.
3424
3706
 
3425
3707
  ---
3426
3708
 
@@ -3478,6 +3760,23 @@ Threaded into
3478
3760
 
3479
3761
  ---
3480
3762
 
3763
+ ##### `createComplianceLogBucket`<sup>Optional</sup> <a name="createComplianceLogBucket" id="@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.createComplianceLogBucket"></a>
3764
+
3765
+ ```typescript
3766
+ public readonly createComplianceLogBucket: boolean;
3767
+ ```
3768
+
3769
+ - *Type:* boolean
3770
+ - *Default:* true
3771
+
3772
+ Whether the pipeline stack creates and manages `complianceLogBucketName`.
3773
+
3774
+ Set to `false` during a Blueprint migration to reference an existing, owner-managed bucket.
3775
+ The pipeline then creates neither the bucket nor its bucket policy; the bucket owner must keep
3776
+ the encryption, TLS-enforcement, and S3 server-access-log delivery policy in place.
3777
+
3778
+ ---
3779
+
3481
3780
  ##### `deployerImage`<sup>Optional</sup> <a name="deployerImage" id="@cdklabs/cdk-cicd-wrapper.ResolvedCicdConfig.property.deployerImage"></a>
3482
3781
 
3483
3782
  ```typescript
@@ -3505,7 +3804,8 @@ Pipeline-level default ExternalId presented when assuming a stage's forced `depl
3505
3804
 
3506
3805
  A stage's
3507
3806
  own `DeploymentConfig.externalId` overrides this. A literal or a `resolve:secretsmanager:<arn>`
3508
- reference resolved at synth time.
3807
+ reference resolved at synth time. Secret references currently require the Secrets Manager
3808
+ AWS-managed encryption key; customer-managed KMS keys are not supported without an external grant.
3509
3809
 
3510
3810
  ---
3511
3811
 
@@ -3670,10 +3970,15 @@ const resolvedDeploymentConfig: ResolvedDeploymentConfig = { ... }
3670
3970
  | **Name** | **Type** | **Description** |
3671
3971
  | --- | --- | --- |
3672
3972
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.targets">targets</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget">ResolvedDeploymentTarget</a>[]</code> | The deployment targets, in order. |
3973
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.application">application</a></code> | <code>string</code> | Application name baked into the deployer image. |
3673
3974
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.codeArtifact">codeArtifact</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.CodeArtifactConfig">CodeArtifactConfig</a></code> | Private CodeArtifact repo the CD build authenticates against before `npm ci` (to install the wrapper CLI when it is pre-release / not on public npm). |
3975
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | Default compliance/access-log destination bucket name for targets that do not provide their own. |
3976
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.crossAccountEcrRepositoryPolicyConfigured">crossAccountEcrRepositoryPolicyConfigured</a></code> | <code>boolean</code> | Confirms that owner-side repository policies permit the generated pipeline role to pull every cross-account ECR image referenced by this deployment config. |
3674
3977
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.image">image</a></code> | <code>string</code> | The default deployer image to run targets against (an ECR/OCI reference, tag or digest). |
3675
3978
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.npmRegistry">npmRegistry</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.NpmRegistryConfig">NpmRegistryConfig</a></code> | Generic private npm registry the CD build authenticates against before `npm ci`. |
3979
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.qualifier">qualifier</a></code> | <code>string</code> | Bootstrap qualifier used by the deployer image; |
3676
3980
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.repository">repository</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.Repository">Repository</a></code> | The config-only source repository the CD pipeline watches (where `deploy.config.ts` lives -- no CDK code). Optional: when omitted, the config drives only the local `cdk-cicd deploy --from-image` executor; set it to provision a CD CodePipeline (`cdk-cicd deploy-ci`) whose CodeBuild pulls the image and deploys each target. This is the deploy-side twin of `ResolvedCicdConfig.repository`. |
3981
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.synthesizer">synthesizer</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.SynthesizerConfig">SynthesizerConfig</a></code> | Synthesizer used by the deployer image; must match its `cicd.config`. |
3677
3982
 
3678
3983
  ---
3679
3984
 
@@ -3689,6 +3994,23 @@ The deployment targets, in order.
3689
3994
 
3690
3995
  ---
3691
3996
 
3997
+ ##### `application`<sup>Optional</sup> <a name="application" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.application"></a>
3998
+
3999
+ ```typescript
4000
+ public readonly application: string;
4001
+ ```
4002
+
4003
+ - *Type:* string
4004
+
4005
+ Application name baked into the deployer image.
4006
+
4007
+ Optional for the default synthesizer; required
4008
+ (or supply `synthesizer.appId`) when the image uses `APP_STAGING` for direct `deploy --from-image`.
4009
+ The generated Repo 2 CodePipeline itself supports only `DEFAULT`. Direct APP_STAGING targets can
4010
+ configure deployment roles, but cannot attach an ExternalId to the deployment role.
4011
+
4012
+ ---
4013
+
3692
4014
  ##### `codeArtifact`<sup>Optional</sup> <a name="codeArtifact" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.codeArtifact"></a>
3693
4015
 
3694
4016
  ```typescript
@@ -3703,6 +4025,35 @@ Same shape as the pipeline-config `codeArtifact`.
3703
4025
 
3704
4026
  ---
3705
4027
 
4028
+ ##### `complianceLogBucketName`<sup>Optional</sup> <a name="complianceLogBucketName" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.complianceLogBucketName"></a>
4029
+
4030
+ ```typescript
4031
+ public readonly complianceLogBucketName: string;
4032
+ ```
4033
+
4034
+ - *Type:* string
4035
+
4036
+ Default compliance/access-log destination bucket name for targets that do not provide their own.
4037
+
4038
+ Repo 2 references an existing bucket; it does not create one. A target using this default must
4039
+ have a concrete account and exactly one concrete Region so S3's same-account/same-Region delivery
4040
+ requirement can be verified. Targets in other environments may override the name individually.
4041
+
4042
+ ---
4043
+
4044
+ ##### `crossAccountEcrRepositoryPolicyConfigured`<sup>Optional</sup> <a name="crossAccountEcrRepositoryPolicyConfigured" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.crossAccountEcrRepositoryPolicyConfigured"></a>
4045
+
4046
+ ```typescript
4047
+ public readonly crossAccountEcrRepositoryPolicyConfigured: boolean;
4048
+ ```
4049
+
4050
+ - *Type:* boolean
4051
+ - *Default:* false
4052
+
4053
+ Confirms that owner-side repository policies permit the generated pipeline role to pull every cross-account ECR image referenced by this deployment config.
4054
+
4055
+ ---
4056
+
3706
4057
  ##### `image`<sup>Optional</sup> <a name="image" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.image"></a>
3707
4058
 
3708
4059
  ```typescript
@@ -3734,6 +4085,20 @@ pipeline-config `npmRegistry`.
3734
4085
 
3735
4086
  ---
3736
4087
 
4088
+ ##### `qualifier`<sup>Optional</sup> <a name="qualifier" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.qualifier"></a>
4089
+
4090
+ ```typescript
4091
+ public readonly qualifier: string;
4092
+ ```
4093
+
4094
+ - *Type:* string
4095
+
4096
+ Bootstrap qualifier used by the deployer image;
4097
+
4098
+ derived from `application` when omitted.
4099
+
4100
+ ---
4101
+
3737
4102
  ##### `repository`<sup>Optional</sup> <a name="repository" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.repository"></a>
3738
4103
 
3739
4104
  ```typescript
@@ -3746,6 +4111,21 @@ The config-only source repository the CD pipeline watches (where `deploy.config.
3746
4111
 
3747
4112
  ---
3748
4113
 
4114
+ ##### `synthesizer`<sup>Optional</sup> <a name="synthesizer" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentConfig.property.synthesizer"></a>
4115
+
4116
+ ```typescript
4117
+ public readonly synthesizer: SynthesizerConfig;
4118
+ ```
4119
+
4120
+ - *Type:* <a href="#@cdklabs/cdk-cicd-wrapper.SynthesizerConfig">SynthesizerConfig</a>
4121
+
4122
+ Synthesizer used by the deployer image; must match its `cicd.config`.
4123
+
4124
+ Optional for compatibility with pre-synthesizer Repo 2 configs; consumers must treat omission
4125
+ as `SynthesizerType.DEFAULT`.
4126
+
4127
+ ---
4128
+
3749
4129
  ### ResolvedDeploymentTarget <a name="ResolvedDeploymentTarget" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget"></a>
3750
4130
 
3751
4131
  A resolved deployment target for container mode (Repo 2): a stage to deploy the pinned image against, with its own environment and optional forced roles.
@@ -3769,6 +4149,9 @@ const resolvedDeploymentTarget: ResolvedDeploymentTarget = { ... }
3769
4149
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.env">env</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.StageEnvironment">StageEnvironment</a></code> | Where this target deploys. |
3770
4150
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.manualApproval">manualApproval</a></code> | <code>boolean</code> | Whether a manual approval gates this target. |
3771
4151
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.stage">stage</a></code> | <code>string</code> | The stage in the image's app to deploy (passed to the in-container `cdk-cicd deploy --stage`). |
4152
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketAccount">complianceLogBucketAccount</a></code> | <code>string</code> | Account containing `complianceLogBucketName`. |
4153
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | Compliance/access-log destination bucket for this target, after applying the deployment-wide default. |
4154
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketRegion">complianceLogBucketRegion</a></code> | <code>string</code> | Region containing `complianceLogBucketName`. |
3772
4155
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.deployment">deployment</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.DeploymentConfig">DeploymentConfig</a></code> | Forced roles for this target, if any. |
3773
4156
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.image">image</a></code> | <code>string</code> | The deployer image (tag/digest) to run for THIS target, overriding the config-level `image`. |
3774
4157
 
@@ -3810,6 +4193,45 @@ The stage in the image's app to deploy (passed to the in-container `cdk-cicd dep
3810
4193
 
3811
4194
  ---
3812
4195
 
4196
+ ##### `complianceLogBucketAccount`<sup>Optional</sup> <a name="complianceLogBucketAccount" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketAccount"></a>
4197
+
4198
+ ```typescript
4199
+ public readonly complianceLogBucketAccount: string;
4200
+ ```
4201
+
4202
+ - *Type:* string
4203
+
4204
+ Account containing `complianceLogBucketName`.
4205
+
4206
+ ---
4207
+
4208
+ ##### `complianceLogBucketName`<sup>Optional</sup> <a name="complianceLogBucketName" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketName"></a>
4209
+
4210
+ ```typescript
4211
+ public readonly complianceLogBucketName: string;
4212
+ ```
4213
+
4214
+ - *Type:* string
4215
+
4216
+ Compliance/access-log destination bucket for this target, after applying the deployment-wide default.
4217
+
4218
+ When set, `complianceLogBucketAccount` and `complianceLogBucketRegion` are also set and
4219
+ exactly match this target's concrete, single-Region environment.
4220
+
4221
+ ---
4222
+
4223
+ ##### `complianceLogBucketRegion`<sup>Optional</sup> <a name="complianceLogBucketRegion" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.complianceLogBucketRegion"></a>
4224
+
4225
+ ```typescript
4226
+ public readonly complianceLogBucketRegion: string;
4227
+ ```
4228
+
4229
+ - *Type:* string
4230
+
4231
+ Region containing `complianceLogBucketName`.
4232
+
4233
+ ---
4234
+
3813
4235
  ##### `deployment`<sup>Optional</sup> <a name="deployment" id="@cdklabs/cdk-cicd-wrapper.ResolvedDeploymentTarget.property.deployment"></a>
3814
4236
 
3815
4237
  ```typescript
@@ -3989,12 +4411,28 @@ const stageStackNameOptions: StageStackNameOptions = { ... }
3989
4411
 
3990
4412
  | **Name** | **Type** | **Description** |
3991
4413
  | --- | --- | --- |
4414
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.preserveStageCase">preserveStageCase</a></code> | <code>boolean</code> | Preserve the stage segment's original casing. |
3992
4415
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.stage">stage</a></code> | <code>string</code> | The stage to fold into the name. |
3993
4416
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.stageFirst">stageFirst</a></code> | <code>boolean</code> | Put the stage BEFORE the base (`<stage>-<base>`) instead of after. |
3994
4417
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.uppercaseStage">uppercaseStage</a></code> | <code>boolean</code> | Uppercase the stage segment. |
3995
4418
 
3996
4419
  ---
3997
4420
 
4421
+ ##### `preserveStageCase`<sup>Optional</sup> <a name="preserveStageCase" id="@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.preserveStageCase"></a>
4422
+
4423
+ ```typescript
4424
+ public readonly preserveStageCase: boolean;
4425
+ ```
4426
+
4427
+ - *Type:* boolean
4428
+
4429
+ Preserve the stage segment's original casing.
4430
+
4431
+ Use this only to match an existing stack whose stage
4432
+ id was custom-case; the backward-compatible default lowercases the segment.
4433
+
4434
+ ---
4435
+
3998
4436
  ##### `stage`<sup>Optional</sup> <a name="stage" id="@cdklabs/cdk-cicd-wrapper.StageStackNameOptions.property.stage"></a>
3999
4437
 
4000
4438
  ```typescript
@@ -4058,7 +4496,8 @@ const supportResourcesProps: SupportResourcesProps = { ... }
4058
4496
 
4059
4497
  | **Name** | **Type** | **Description** |
4060
4498
  | --- | --- | --- |
4061
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | The name of the compliance/access-log bucket -- Blueprint's `IComplianceBucket.bucketName` (`ComplianceBucketProvider`). Required only if `complianceLogBucket` is read; an explicit, predictable name is what lets other buckets' S3 server-access-logging destination (and Blueprint's cross-region name-substitution convention for multi-region deployments) point at it. |
4499
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.complianceLogBucketName">complianceLogBucketName</a></code> | <code>string</code> | The name of the compliance/access-log bucket -- Blueprint's `IComplianceBucket.bucketName` (`ComplianceBucketProvider`). Required only if `complianceLogBucket` is read; an explicit, predictable name is what lets same-account, same-Region application buckets point their S3 server-access logging at it without creating CloudFormation cross-stack references. |
4500
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.createComplianceLogBucket">createComplianceLogBucket</a></code> | <code>boolean</code> | Whether this construct creates and manages `complianceLogBucketName`. |
4062
4501
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.removalPolicy">removalPolicy</a></code> | <code>aws-cdk-lib.RemovalPolicy</code> | Removal policy for the support resources. |
4063
4502
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.useProxy">useProxy</a></code> | <code>boolean</code> | Whether an HTTP(S) proxy is configured (`ResolvedCicdConfig.proxy`). A managed VPC uses isolated subnets when true, matching Blueprint's `VPCProvider`. |
4064
4503
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.vpc">vpc</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.VpcConfig">VpcConfig</a></code> | VPC every CodeBuild project the pipeline creates runs in, if configured. |
@@ -4073,7 +4512,26 @@ public readonly complianceLogBucketName: string;
4073
4512
 
4074
4513
  - *Type:* string
4075
4514
 
4076
- The name of the compliance/access-log bucket -- Blueprint's `IComplianceBucket.bucketName` (`ComplianceBucketProvider`). Required only if `complianceLogBucket` is read; an explicit, predictable name is what lets other buckets' S3 server-access-logging destination (and Blueprint's cross-region name-substitution convention for multi-region deployments) point at it.
4515
+ The name of the compliance/access-log bucket -- Blueprint's `IComplianceBucket.bucketName` (`ComplianceBucketProvider`). Required only if `complianceLogBucket` is read; an explicit, predictable name is what lets same-account, same-Region application buckets point their S3 server-access logging at it without creating CloudFormation cross-stack references.
4516
+
4517
+ ---
4518
+
4519
+ ##### `createComplianceLogBucket`<sup>Optional</sup> <a name="createComplianceLogBucket" id="@cdklabs/cdk-cicd-wrapper.SupportResourcesProps.property.createComplianceLogBucket"></a>
4520
+
4521
+ ```typescript
4522
+ public readonly createComplianceLogBucket: boolean;
4523
+ ```
4524
+
4525
+ - *Type:* boolean
4526
+ - *Default:* true
4527
+
4528
+ Whether this construct creates and manages `complianceLogBucketName`.
4529
+
4530
+ Set to `false` to reference a pre-existing, owner-managed Blueprint compliance bucket. Imported
4531
+ buckets synthesize no `AWS::S3::Bucket` or `AWS::S3::BucketPolicy`; the owner must maintain the
4532
+ bucket's same-account/same-Region placement, SSE-S3 encryption, TLS enforcement, public-access
4533
+ block, disabled Object Lock and Requester Pays settings, and S3 server-access-log delivery policy.
4534
+ A name-only CDK import cannot inspect or validate those live settings.
4077
4535
 
4078
4536
  ---
4079
4537
 
@@ -4136,6 +4594,7 @@ const synthesizerConfig: SynthesizerConfig = { ... }
4136
4594
  | **Name** | **Type** | **Description** |
4137
4595
  | --- | --- | --- |
4138
4596
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.SynthesizerConfig.property.type">type</a></code> | <code><a href="#@cdklabs/cdk-cicd-wrapper.SynthesizerType">SynthesizerType</a></code> | The synthesizer to install. |
4597
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.SynthesizerConfig.property.appId">appId</a></code> | <code>string</code> | Application-unique id for `APP_STAGING` resources. |
4139
4598
 
4140
4599
  ---
4141
4600
 
@@ -4151,6 +4610,21 @@ The synthesizer to install.
4151
4610
 
4152
4611
  ---
4153
4612
 
4613
+ ##### `appId`<sup>Optional</sup> <a name="appId" id="@cdklabs/cdk-cicd-wrapper.SynthesizerConfig.property.appId"></a>
4614
+
4615
+ ```typescript
4616
+ public readonly appId: string;
4617
+ ```
4618
+
4619
+ - *Type:* string
4620
+
4621
+ Application-unique id for `APP_STAGING` resources.
4622
+
4623
+ Defaults to `application`; the alpha
4624
+ synthesizer normalizes it to a lowercase, dash-separated value of at most 20 characters.
4625
+
4626
+ ---
4627
+
4154
4628
  ### VpcConfig <a name="VpcConfig" id="@cdklabs/cdk-cicd-wrapper.VpcConfig"></a>
4155
4629
 
4156
4630
  VPC configuration for the pipeline's own CodeBuild projects (Blueprint `IVpcConfig`, migrated from `VPCProvider`).
@@ -4270,7 +4744,10 @@ Undefined for a looked-up VPC (CodeBuild then selects private subnets).
4270
4744
 
4271
4745
  - *Implements:* aws-cdk-lib.IAspect
4272
4746
 
4273
- Configures S3 server access logging (destination + prefix) on every L1 `CfnBucket` it visits that does not already set a logging destination, matching Blueprint's default-on `AccessLogsForBucketPlugin`.
4747
+ Configures S3 server access logging on every L1 `CfnBucket` it visits.
4748
+
4749
+ The compliance destination
4750
+ always wins; an existing user prefix is preserved, otherwise a bucket-specific prefix is generated.
4274
4751
 
4275
4752
  #### Initializers <a name="Initializers" id="@cdklabs/cdk-cicd-wrapper.AccessLogsForBucketAspect.Initializer"></a>
4276
4753
 
@@ -5490,14 +5967,14 @@ How the pushed image is tagged.
5490
5967
 
5491
5968
  | **Name** | **Description** |
5492
5969
  | --- | --- |
5493
- | <code><a href="#@cdklabs/cdk-cicd-wrapper.ImageTagStrategy.GIT_SHA">GIT_SHA</a></code> | Tag with the resolved source commit sha (CODEBUILD_RESOLVED_SOURCE_VERSION). |
5970
+ | <code><a href="#@cdklabs/cdk-cicd-wrapper.ImageTagStrategy.GIT_SHA">GIT_SHA</a></code> | Tag with the resolved Git commit SHA, or a deterministic SHA-256 of a non-Git source revision. |
5494
5971
  | <code><a href="#@cdklabs/cdk-cicd-wrapper.ImageTagStrategy.LATEST">LATEST</a></code> | Tag `latest` only. |
5495
5972
 
5496
5973
  ---
5497
5974
 
5498
5975
  ##### `GIT_SHA` <a name="GIT_SHA" id="@cdklabs/cdk-cicd-wrapper.ImageTagStrategy.GIT_SHA"></a>
5499
5976
 
5500
- Tag with the resolved source commit sha (CODEBUILD_RESOLVED_SOURCE_VERSION).
5977
+ Tag with the resolved Git commit SHA, or a deterministic SHA-256 of a non-Git source revision.
5501
5978
 
5502
5979
  The default.
5503
5980
 
@@ -5637,5 +6114,9 @@ Which stack synthesizer the wrapper installs.
5637
6114
 
5638
6115
  `AppStagingSynthesizer` -- opt-in, still alpha.
5639
6116
 
6117
+ Supported for direct/local application
6118
+ deployments and Repo 1 image synthesis; wrapper-generated deployment pipelines reject it.
6119
+ Its staging support stack cannot honor a configured deploy or CloudFormation execution role.
6120
+
5640
6121
  ---
5641
6122