@codedrifters/configulator 0.0.430 → 0.0.431

package/lib/index.d.mts

@@ -12573,6 +12573,35 @@ interface DeployWorkflowOptions {
      * @default discovers all targets using stageType
      */
     readonly awsDeploymentTargets?: Array<AwsDeploymentTarget>;
+    /**
+     * Key each deploy job's concurrency group on the branch as well as the
+     * deployment target.
+     *
+     * A deploy job's group is otherwise the target coordinates alone
+     * (`<stage>-<role>-deploy-<project>-<account>-<region>`), and GitHub scopes
+     * concurrency groups to the *repository* — so one group serializes every run
+     * of every workflow carrying that job, on every branch. That is what you want
+     * when each branch deploys the same stacks.
+     *
+     * It is not what you want when the CDK app derives its stack names from the
+     * branch: two branches then update entirely separate stacks while queueing
+     * behind one lock. Setting this appends the branch, so branches deploy in
+     * parallel and same-branch runs still serialize.
+     *
+     * Enabling this lets per-branch deploys run concurrently into the *same* AWS
+     * account, so anything they share outside their own stacks — a parent hosted
+     * zone, an account-level singleton — has to tolerate concurrent mutation.
+     *
+     * Applies to the deploy job only. The `plan-apply` gate's apply job keeps the
+     * unsuffixed group: an apply is dispatched from whatever ref the operator
+     * happens to be on, which says nothing about the branch that was planned, so
+     * a branch key there would weaken the mutual exclusion rather than sharpen
+     * it.
+     *
+     * @see `docs/packages/@codedrifters/configulator/workflows/aws-deploy-workflow.md`
+     * @default false - the group is the deployment target alone
+     */
+    readonly branchScopedConcurrency?: boolean;
     /**
      * Existing workflow, useful if we're tacking deployments onto an existing
      * build workflow
@@ -12700,6 +12729,10 @@ declare class AwsDeployWorkflow extends Component {
      * never have to re-apply the defaults.
      */
     readonly diffOptions: Required<DeployDiffOptions>;
+    /**
+     * Whether each deploy job's concurrency group carries the branch.
+     */
+    readonly branchScopedConcurrency: boolean;
     /**
      * Repository this workflow's cloud-touching jobs are pinned to, if any.
      */
@@ -12738,6 +12771,20 @@ declare class AwsDeployWorkflow extends Component {
      * header so dev/stage/prod comments don't collide on the same PR.
      */
     private buildJobName;
+    /**
+     * Build a deploy job's `concurrency` setting from its job name.
+     *
+     * Two shapes, deliberately:
+     *
+     * - Unscoped (the default) stays the bare string the job has always carried,
+     *   so an existing consumer's workflow is byte-identical.
+     * - Branch-scoped spells out `cancel-in-progress: false` rather than leaning
+     *   on GitHub's default, the same way the apply job does. A group keyed on
+     *   the branch reads like a "cancel superseded pushes" group, and that is the
+     *   one thing it must not be — cancelling a half-finished `cdk deploy`
+     *   strands a CloudFormation stack mid-update.
+     */
+    private buildDeployConcurrency;
     /**
      * Build the deterministic GitHub Actions job name for a target's apply job.
      * Mirrors {@link buildJobName} with an `apply` verb.

package/lib/index.d.ts

@@ -12622,6 +12622,35 @@ interface DeployWorkflowOptions {
      * @default discovers all targets using stageType
      */
     readonly awsDeploymentTargets?: Array<AwsDeploymentTarget>;
+    /**
+     * Key each deploy job's concurrency group on the branch as well as the
+     * deployment target.
+     *
+     * A deploy job's group is otherwise the target coordinates alone
+     * (`<stage>-<role>-deploy-<project>-<account>-<region>`), and GitHub scopes
+     * concurrency groups to the *repository* — so one group serializes every run
+     * of every workflow carrying that job, on every branch. That is what you want
+     * when each branch deploys the same stacks.
+     *
+     * It is not what you want when the CDK app derives its stack names from the
+     * branch: two branches then update entirely separate stacks while queueing
+     * behind one lock. Setting this appends the branch, so branches deploy in
+     * parallel and same-branch runs still serialize.
+     *
+     * Enabling this lets per-branch deploys run concurrently into the *same* AWS
+     * account, so anything they share outside their own stacks — a parent hosted
+     * zone, an account-level singleton — has to tolerate concurrent mutation.
+     *
+     * Applies to the deploy job only. The `plan-apply` gate's apply job keeps the
+     * unsuffixed group: an apply is dispatched from whatever ref the operator
+     * happens to be on, which says nothing about the branch that was planned, so
+     * a branch key there would weaken the mutual exclusion rather than sharpen
+     * it.
+     *
+     * @see `docs/packages/@codedrifters/configulator/workflows/aws-deploy-workflow.md`
+     * @default false - the group is the deployment target alone
+     */
+    readonly branchScopedConcurrency?: boolean;
     /**
      * Existing workflow, useful if we're tacking deployments onto an existing
      * build workflow
@@ -12749,6 +12778,10 @@ declare class AwsDeployWorkflow extends Component {
      * never have to re-apply the defaults.
      */
     readonly diffOptions: Required<DeployDiffOptions>;
+    /**
+     * Whether each deploy job's concurrency group carries the branch.
+     */
+    readonly branchScopedConcurrency: boolean;
     /**
      * Repository this workflow's cloud-touching jobs are pinned to, if any.
      */
@@ -12787,6 +12820,20 @@ declare class AwsDeployWorkflow extends Component {
      * header so dev/stage/prod comments don't collide on the same PR.
      */
     private buildJobName;
+    /**
+     * Build a deploy job's `concurrency` setting from its job name.
+     *
+     * Two shapes, deliberately:
+     *
+     * - Unscoped (the default) stays the bare string the job has always carried,
+     *   so an existing consumer's workflow is byte-identical.
+     * - Branch-scoped spells out `cancel-in-progress: false` rather than leaning
+     *   on GitHub's default, the same way the apply job does. A group keyed on
+     *   the branch reads like a "cancel superseded pushes" group, and that is the
+     *   one thing it must not be — cancelling a half-finished `cdk deploy`
+     *   strands a CloudFormation stack mid-update.
+     */
+    private buildDeployConcurrency;
     /**
      * Build the deterministic GitHub Actions job name for a target's apply job.
      * Mirrors {@link buildJobName} with an `apply` verb.

package/lib/index.js

@@ -42928,6 +42928,7 @@ var renderSetupPnpm = (pnpmVersion) => {
 
 // src/workflows/aws-deploy-workflow.ts
 var PROD_DEPLOY_NAME = "prod-deploy";
+var BRANCH_NAME_EXPRESSION = "${{ github.head_ref || github.ref_name }}";
 var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Component {
   constructor(project, options = {}) {
     super(project);
@@ -42958,6 +42959,28 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Compone
         target.region
       ].join("-");
     };
+    /**
+     * Build a deploy job's `concurrency` setting from its job name.
+     *
+     * Two shapes, deliberately:
+     *
+     * - Unscoped (the default) stays the bare string the job has always carried,
+     *   so an existing consumer's workflow is byte-identical.
+     * - Branch-scoped spells out `cancel-in-progress: false` rather than leaning
+     *   on GitHub's default, the same way the apply job does. A group keyed on
+     *   the branch reads like a "cancel superseded pushes" group, and that is the
+     *   one thing it must not be — cancelling a half-finished `cdk deploy`
+     *   strands a CloudFormation stack mid-update.
+     */
+    this.buildDeployConcurrency = (deployJobName) => {
+      if (!this.branchScopedConcurrency) {
+        return deployJobName;
+      }
+      return {
+        group: `${deployJobName}-${BRANCH_NAME_EXPRESSION}`,
+        "cancel-in-progress": false
+      };
+    };
     /**
      * Build the deterministic GitHub Actions job name for a target's apply job.
      * Mirrors {@link buildJobName} with an `apply` verb.
@@ -43087,6 +43110,13 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Compone
          * same-target deploy. `cancel-in-progress` is spelled out rather than
          * left to GitHub's default: cancelling a half-finished `cdk deploy`
          * strands a CloudFormation stack mid-update.
+         *
+         * `branchScopedConcurrency` deliberately does not reach here. An apply is
+         * dispatched from whatever ref the operator happens to be on — unrelated
+         * to the branch the nominated plan ran against, which is the only branch
+         * that describes what is about to be deployed. Keying on the dispatch ref
+         * would hand out separate locks to applies of the same target, so the
+         * unsuffixed group stays.
          */
         concurrency: {
           group: this.buildJobName(target),
@@ -43352,6 +43382,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Compone
       artifact: options.diff?.artifact ?? true,
       summary: options.diff?.summary ?? true
     };
+    this.branchScopedConcurrency = options.branchScopedConcurrency ?? false;
     this.environmentName = resolveEnvironmentGate(
       options.gate,
       options.environmentName,
@@ -43415,7 +43446,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Compone
        * Set GIT_BRANCH_NAME so Turborepo remote cache hashes match between local and CI.
        */
       env: {
-        GIT_BRANCH_NAME: "${{ github.head_ref || github.ref_name }}",
+        GIT_BRANCH_NAME: BRANCH_NAME_EXPRESSION,
         ...options.buildWorkflowOptions?.env,
         ...buildWorkflowOptions?.env
       },
@@ -43505,7 +43536,7 @@ var AwsDeployWorkflow = class _AwsDeployWorkflow extends import_projen29.Compone
             pullRequests: import_workflows_model7.JobPermission.WRITE
           },
           ...this.environmentName ? { environment: this.environmentName } : void 0,
-          concurrency: deployJobName,
+          concurrency: this.buildDeployConcurrency(deployJobName),
           if: jobCondition,
           steps: [...this.deploySteps(target)]
         });