RFC: GitHub Actions CI/CD with protected deployment environment and approval gates

[scottschreckengaust]

RFC: Automated Deployment Pipeline with Protected Environments

Status: Core complete — remaining work tracked in #72 (revised per feedback)

Author: @scottschreckengaust

Related: #70 (context stack names), #72 (ephemeral cleanup)

---

Current state (reconciled 2026-06-05)

The core deploy pipeline is delivered and on main:

• ✅ Phase 1 — Foundation (OIDC provider, deploy environment, GH→bootstrap-role assumption, account bootstrap)
• ✅ Phase 2 — Build pipeline (per-compute_type synth, immutable cdk-<type>.out artifacts, 13 github:* tags) — PRs feat(ci): synth-per-variant build with github:* context in artifact #91, feat(cdk): add 4 additional github:* resource tags #93, feat(ci): rename computeVariant to compute_type and apply as resource tag #97
• ✅ Phase 3 — Deploy pipeline (artifact-based deploy, label-driven matrix, OIDC, baseline diff) — PR feat(ci): add deploy pipeline with OIDC, dynamic stack naming, and deploy-intent artifact #98
  • ⬜ One item left: release flow (draft → deploy → tag → publish)
• ⬜ Phase 4 — Cleanup (ephemeral stacks) — NOT done. Tracked by feat: automated ephemeral stack cleanup (scheduled) #72. Partial work in draft PR feat(ops): automated ephemeral stack cleanup script #109 (manual scripts/cleanup-ephemeral-stacks.sh only; no EventBridge schedule, no CloudWatch audit, no CDK construct, no tests). PR feat(ops): automated ephemeral stack cleanup script #109 is stale (untouched since 2026-05-18).
• ⬜ Phase 5 — Observability (CloudWatch alarms for stack count/ENI leaks/cost; approval checklist in CONTRIBUTING.md)

Next to pick up: ephemeral cleanup automation (Phase 4) — see acceptance criteria in #72, building on the script in PR #109.

---

Summary

Establish a GitHub Actions deployment pipeline that:

1. Builds and synthesizes CDK once per compute_type in build.yml (always all registered types)
2. Stores cdk-<compute_type>.out as immutable deployment artifacts (synth once, deploy exact artifact)
3. Gates all deployments behind a protected GitHub environment (deploy) requiring manual approval — triggered by deploy label (with optional type qualifiers)
4. Deploys to AWS using OIDC federation assuming CDK bootstrap roles (no long-lived credentials)
5. Stack naming: main-<compute_type>-prd for production, ephemeral for PRs/branches
6. On successful deployment: creates a GitHub Release (drafted → published) with tagged main and cdk-*.out artifacts
7. Cleanup targets stacks tagged with github:* context keys (presence of any github:sha != none), gated behind approval with cancel-in-progress concurrency

---

Decisions (from discussion)

Question	Decision
PR deployments	Opt-in via deploy label (with optional type qualifiers)
Synth strategy	Once in build.yml for ALL registered compute_types, deploy the exact artifact — no re-synth
Cleanup approval	Always manually gated — later runs cancel prior pending requests
Cost gate	No — resource review in approval is sufficient
Permissions boundary	Yes — use CDK bootstrap roles (deploy, lookup, file-publishing, image-publishing)
main deploy approval	Always require — never skip, even after PR merge
Deploy selection	Label-driven: deploy = all registered types, deploy:<type> = only that type
Baselines	Per-compute_type against main-<compute_type>-prd — stored as release artifacts

---

Design

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│  GitHub Actions                                                      │
│                                                                      │
│  build.yml (CI) — every push/PR                                      │
│  ├─ steps: install → compile → test → lint → synth (per compute_type)│
│  ├─ matrix: ALL registered compute_types (static list, always built) │
│  ├─ artifact: cdk-<compute_type>.out (immutable, uploaded per leg)   │
│  └─ output: stack_name, is_protected, compute_type                   │
│                                                                      │
│  deploy.yml (CD) — on `deploy` label OR main merge                   │
│  ├─ trigger: label added + build success, OR push to main            │
│  ├─ environment: "deploy" (ALWAYS requires approval, no bypass)      │
│  ├─ matrix: filtered by labels (deploy=all, deploy:<type>=one)       │
│  ├─ steps:                                                           │
│  │   ├─ download cdk-<compute_type>.out artifact (exact build output)│
│  │   ├─ configure-aws-credentials (OIDC → CDK bootstrap roles)      │
│  │   ├─ baseline-diff (compare vs last release baseline)             │
│  │   ├─ post diff summary to deployment log                          │
│  │   ├─ cdk deploy --app cdk-<compute_type>.out --require-approval never │
│  │   └─ on success: draft release → tag → attach artifacts → publish │
│  └─ concurrency: one deploy at a time per stack                      │
│                                                                      │
│  cleanup.yml                                                         │
│  ├─ trigger: schedule (every 4h) + workflow_dispatch                 │
│  ├─ environment: "deploy" (ALWAYS requires approval)                 │
│  ├─ concurrency: cancel-in-progress (later runs cancel prior)        │
│  └─ steps: find stacks with github:* tags → force-detach ENIs → del │
└─────────────────────────────────────────────────────────────────────┘
         │
         │ OIDC (aws-actions/configure-aws-credentials)
         │ role-to-assume: CDK deploy role
         ▼
┌─────────────────────────────────────────────────────────────────────┐
│  AWS Account                                                         │
│  ├─ IAM OIDC Provider (token.actions.githubusercontent.com)          │
│  ├─ CDK Bootstrap Roles (permissions boundary):                      │
│  │   ├─ cdk-hnb659fds-deploy-role-*                                  │
│  │   ├─ cdk-hnb659fds-lookup-role-*                                  │
│  │   ├─ cdk-hnb659fds-file-publishing-role-*                         │
│  │   └─ cdk-hnb659fds-image-publishing-role-*                        │
│  ├─ CloudFormation Stacks (tagged: github:sha != 'none')             │
│  │   ├─ main-agentcore-prd (protected, terminationProtection=true)   │
│  │   ├─ main-ecs-prd (protected, terminationProtection=true)         │
│  │   ├─ pr-42-abc1234-agentcore (ephemeral, tagged)                  │
│  │   └─ commit-abc1234-ecs (ephemeral, tagged)                       │
│  └─ CDK Bootstrap (cdk-toolkit stack)                                │
└─────────────────────────────────────────────────────────────────────┘

---

Label-Driven Deploy Selection

Key principle: Build ALL, deploy selectively

build.yml always synthesizes all registered compute_types (today: [agentcore]). Labels only control what deploy.yml deploys.

Labels

Label	Types deployed	Use case
deploy	All registered types	Standard full deployment
deploy:agentcore	agentcore only	Deploy only agentcore
deploy:ecs	ecs only	Deploy only ECS (when available)
deploy:*	All (same as deploy)	Explicit "all" synonym
No deploy* label	Nothing deployed	Default (CI only)

Resolution logic (in deploy.yml)

- name: Resolve deploy targets from labels
  id: targets
  run: |
    LABELS='${{ toJson(github.event.pull_request.labels.*.name) }}'
    # All registered compute_types (must match build.yml matrix)
    ALL_TYPES='["agentcore"]'

    if echo "$LABELS" | jq -e 'index("deploy:*")' > /dev/null; then
      # deploy:* = all (explicit synonym)
      echo "matrix=$ALL_TYPES" >> "$GITHUB_OUTPUT"
    elif echo "$LABELS" | jq -e '[.[] | select(startswith("deploy:"))] | length > 0' > /dev/null; then
      # Specific type labels — deploy only those
      TYPES=$(echo "$LABELS" | jq '[.[] | select(startswith("deploy:")) | ltrimstr("deploy:")]')
      echo "matrix=$TYPES" >> "$GITHUB_OUTPUT"
    elif echo "$LABELS" | jq -e 'index("deploy")' > /dev/null; then
      # Plain "deploy" = all registered types
      echo "matrix=$ALL_TYPES" >> "$GITHUB_OUTPUT"
    else
      echo 'matrix=[]' >> "$GITHUB_OUTPUT"
    fi

---

Release Flow

Successful deployments from main produce GitHub Releases:

main merge
  → build.yml (synth ALL registered compute_types in matrix)
  → upload artifacts: cdk-agentcore.out, (cdk-ecs.out when available, ...)
  → deploy.yml (approval gate — downloads exact artifacts, label filters which deploy)
  → successful deployment
  → Draft Release created:
      Tag: v<date>-<short-sha> (e.g. v2026.05.11-abc1234)
      Assets:
        - cdk-agentcore.out.tar.gz
        - (cdk-ecs.out.tar.gz when available)
        - agentcore.resource-types.json (baseline)
        - (ecs.resource-types.json when available)
  → Publish Release

Baselines live in releases, not in the repo. The diff step downloads the baseline from the latest published release for that compute_type:

- name: Download baseline from latest release
  run: |
    LATEST=$(gh release view --json tagName -q .tagName 2>/dev/null || echo "")
    if [[ -n "$LATEST" ]]; then
      gh release download "$LATEST" \
        --pattern "${{ matrix.compute_type }}.resource-types.json" \
        --dir /tmp/baseline/ || true
    fi

This means:

• No baseline commits polluting the repo history
• Baselines are immutable (tied to a release tag)
• First deploy (no prior release) has no baseline → everything shows as "new" (correct)
• Rollback = re-deploy from a prior release's cdk-*.out artifact

---

Synth-Once, Deploy-Exact Artifact

The cdk.out is synthesized exactly once per compute_type during build.yml. The deploy.yml never re-synths — it downloads and deploys the exact artifact:

# build.yml — always synths ALL registered types
strategy:
  matrix:
    compute_type: [agentcore]  # extend when new types are ready

# Context is generated into cdk/cdk.context.json before build
- name: Generate CDK context
  run: |
    jq -n \
      --arg compute_type "${{ matrix.compute_type }}" \
      --arg stackName "backgroundagent-dev" \
      --arg sha "$TAG_SHA" \
      ... \
      '{ "compute_type": $compute_type, "stackName": $stackName, "github:sha": $sha, ... }' \
      > cdk/cdk.context.json

- uses: actions/upload-artifact@v4
  with:
    name: cdk-${{ matrix.compute_type }}-out
    path: |
      cdk/cdk.out/
      cdk/cdk.context.json

# deploy.yml (no synth — uses exact artifact from build)
- uses: actions/download-artifact@v4
  with:
    name: cdk-${{ matrix.compute_type }}-out
    path: cdk-${{ matrix.compute_type }}.out/

- name: Deploy
  run: npx cdk deploy --app cdk-${{ matrix.compute_type }}.out --all --require-approval never

This guarantees what was tested in CI is exactly what gets deployed — no new Date() drift, no env var differences, no CDK version skew.

---

Permissions: CDK Bootstrap Role Assumption

The GitHub OIDC role only needs permission to assume the CDK bootstrap roles. This is the CDK security best practice:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "sts:AssumeRole",
      "Resource": [
        "arn:aws:iam::ACCOUNT:role/cdk-hnb659fds-deploy-role-*",
        "arn:aws:iam::ACCOUNT:role/cdk-hnb659fds-lookup-role-*",
        "arn:aws:iam::ACCOUNT:role/cdk-hnb659fds-file-publishing-role-*",
        "arn:aws:iam::ACCOUNT:role/cdk-hnb659fds-image-publishing-role-*"
      ]
    },
    {
      "Sid": "CleanupENIs",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeNetworkInterfaces",
        "ec2:DetachNetworkInterface",
        "ec2:DeleteNetworkInterface",
        "cloudformation:ListStacks",
        "cloudformation:DescribeStacks",
        "cloudformation:DeleteStack",
        "cloudformation:ListStackResources"
      ],
      "Resource": "*"
    }
  ]
}

Trust policy (OIDC):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Principal": {
      "Federated": "arn:aws:iam::ACCOUNT:oidc-provider/token.actions.githubusercontent.com"
    },
    "Action": "sts:AssumeRoleWithWebIdentity",
    "Condition": {
      "StringEquals": {
        "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
      },
      "StringLike": {
        "token.actions.githubusercontent.com:sub": "repo:aws-samples/sample-autonomous-cloud-coding-agents:*"
      }
    }
  }]
}

---

Stack Naming and Tagging

Git ref	Label	Stack name	Protected
main	(auto)	main-agentcore-prd	true
main	deploy:ecs	main-ecs-prd	true
PR #42	deploy	pr-42-abc1234-agentcore	false
PR #42	deploy:ecs	pr-42-abc1234-ecs	false
Branch push	deploy	commit-abc1234-agentcore	false

All stacks deployed via this pipeline are identified by the 13 github:* tags applied via CDK context (PR #91, #93). Cleanup identifies CI-deployed stacks by checking github:sha != none. Additionally:

Tags.of(stack).add('compute_type', computeType);

The compute_type tag enables per-type baseline queries and cost attribution.

---

GitHub Environment: deploy

Setting	Value	Rationale
Required reviewers	≥1 reviewer, NOT the actor who triggered	Prevents self-approval
Wait timer	0 (manual approval is the gate)	—
Deployment branches	All branches	Allow PR deploys via label
Allow administrators to bypass	No	No bypass for anyone
Prevent self-review	Yes	Enforce separation of duties

Environment secrets:

Secret	Value
AWS_ROLE_ARN	arn:aws:iam::ACCOUNT:role/GitHubActionsCDKRole
AWS_REGION	us-east-1

---

Cleanup Workflow

name: Cleanup Ephemeral Stacks
on:
  schedule:
    - cron: '0 */4 * * *'
  workflow_dispatch:
    inputs:
      max_age_hours:
        description: 'Max age in hours (0 = all non-protected)'
        default: '0'
      dry_run:
        description: 'Dry run mode'
        type: boolean
        default: true

concurrency:
  group: cleanup-ephemeral
  cancel-in-progress: true  # later runs cancel prior pending requests

jobs:
  cleanup:
    runs-on: ubuntu-latest
    environment: deploy  # ALWAYS requires approval
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ secrets.AWS_REGION }}

      - name: Run cleanup
        env:
          MAX_AGE_HOURS: ${{ inputs.max_age_hours || '0' }}
        run: ./scripts/cleanup-ephemeral-stacks.sh --tag-key github:sha --tag-value-not none

---

Resource Baseline and Diff (via Releases)

Diff output example (shown to approver in Step Summary)

## ⚠️ New AWS Resource Types (agentcore)

The following resource types are NEW compared to latest release v2026.05.10-fa647ca:

  + AWS::EKS::Cluster
  + AWS::EKS::Nodegroup
  + AWS::IAM::OpenIDConnectProvider

Approver action: Verify cost model, quotas, security posture, and cleanup behavior.

## Resource count: 47 → 50 (+3)

---

Approval Gate: What Reviewers Should Check

The deployment summary provides:

1. Resource type diff from baseline (new/removed services)
2. Full cdk diff (property-level changes from the synthesized artifact)
3. Compute type and stack name being deployed
4. Labels that triggered the deployment

Per new resource type, verify:

Check	How
Cost model	AWS Pricing / awspricing MCP
Service quotas	aws service-quotas list-service-quotas --service-code <code>
Security posture	Public endpoints? VPC-only? Encryption at rest?
IAM blast radius	What * permissions does CDK grant?
Cleanup behavior	RemovalPolicy.DESTROY? Orphan risk?
Regional availability	Available in target region?

---

Implementation Plan

Phase 1: Foundation

• Create GitHub environment deploy (no self-approval, no bypass, prevent self-review)
• Set up AWS OIDC provider
• Create GitHub Actions role with sts:AssumeRole to CDK bootstrap roles
• CDK bootstrap the target account

Phase 2: Build pipeline

• Add per-compute_type matrix to build.yml (PR feat(ci): synth-per-variant build with github:* context in artifact #91) — currently [agentcore]
• Generate cdk.context.json with all 13 github:* tags + compute_type + stackName (PR feat(ci): synth-per-variant build with github:* context in artifact #91)
• Apply 13 github:* resource tags via CDK context (PR feat(ci): synth-per-variant build with github:* context in artifact #91, feat(cdk): add 4 additional github:* resource tags #93)
• Upload cdk-<compute_type>-out immutable artifact per matrix leg (PR feat(ci): synth-per-variant build with github:* context in artifact #91)
• Read compute_type from context in CDK and apply as resource tag (PR feat(ci): rename computeVariant to compute_type and apply as resource tag #97)
• Rename computeVariant → compute_type in build.yml context generation (PR feat(ci): rename computeVariant to compute_type and apply as resource tag #97)

Phase 3: Deploy pipeline

• Create deploy.yml — downloads exact artifact, never re-synths (PR feat(ci): add deploy pipeline with OIDC, dynamic stack naming, and deploy-intent artifact #98)
• Add label-driven deploy matrix resolution (deploy = all, deploy:<type> = one) (PR feat(ci): add deploy pipeline with OIDC, dynamic stack naming, and deploy-intent artifact #98)
• Implement OIDC → CDK bootstrap role assumption (PR feat(ci): add deploy pipeline with OIDC, dynamic stack naming, and deploy-intent artifact #98)
• Add baseline diff step (download from latest release)
• Add cdk diff output to step summary
• Implement release flow (draft → deploy → tag → publish)

Phase 4: Cleanup

• Add ENI cleanup if necessary to GitHub assumed role
• Update cleanup-ephemeral-stacks.sh to target by github:sha tag presence
• Create cleanup.yml with approval gate and cancel-in-progress
• Schedule every 4h

Phase 5: Observability

• CloudWatch alarms (stack count, ENI leaks, cost)
• Document approval checklist in CONTRIBUTING.md

---

Security Considerations

• No long-lived credentials: OIDC only → assumes CDK bootstrap roles
• Permissions boundary: GitHub role can ONLY assume the 4 CDK bootstrap roles + ENI cleanup
• No self-approval: Enforced at GitHub environment level
• No admin bypass: Even org owners must get approval
• Audit trail: GitHub deployment history + CloudTrail
• Tag-based targeting: Cleanup identifies stacks by github:sha tag (applied to all CI-deployed stacks)
• Termination protection: main-*-prd stacks cannot be accidentally deleted
• Artifact integrity: What CI tested is exactly what gets deployed (no re-synth)

---

References

• aws-actions/configure-aws-credentials — OIDC best practices
• CDK Security Best Practices — bootstrap role pattern
• GitHub Environments — protection rules
• PR fix: allow stackName to change #70 — context stack names
• PR feat(ci): synth-per-variant build with github:* context in artifact #91 — synth-per-variant build with github:* context in artifact
• PR feat(cdk): add 4 additional github:* resource tags #93 — add 4 additional github:* resource tags (13 total)
• Issue feat: automated ephemeral stack cleanup (scheduled) #72 — ephemeral cleanup automation

[scottschreckengaust]

---

Change the target for cleanup by stacks tagged with github instead of by the "description" (stack termination protection will guard those stacks not to be deleted)?

The cleanup job handles all variants — it targets stacks by description ("ABCA Development Stack") regardless of variant prefix.

---

Open Questions

1. Should PR deployments be opt-in (label-triggered) or automatic on every PR?

Yes, I like having a deployment-request to request a deployment - every PR is overkill.

2. Should the cleanup scheduled job require approval or auto-run? (Current proposal: auto for scheduled, approval for manual dispatch)

I like having it be manually gated (even if it triggers and it doesn't run that is okay). Please have the concurrency be set so later runs cancel prior requests (because they do the same thing)

3. Should we add a cost gate (reject deploys if estimated cost exceeds threshold)?

No, the review of what resources are being added and included is sufficient.

4. Should the deploy role use a permissions boundary to prevent escalation?

Absolutely, how does that look like with a CDK deployment? The four seem the most prudent and best-practice security https://docs.aws.amazon.com/cdk/v2/guide/best-practices-security.html:

• "arn:aws:iam:::role/cdk-hnb659fds-deploy-role-*",
• "arn:aws:iam:::role/cdk-hnb659fds-lookup-role-*",
• "arn:aws:iam:::role/cdk-hnb659fds-file-publishing-role-*",
• "arn:aws:iam:::role/cdk-hnb659fds-image-publishing-role-*"

5. For the main → backgroundagent-dev deploy, should we skip approval on merge (trusted after PR review) or always require it?

Always require it and have the stacks be main-<compute_variant>-prd

6. Should variant selection be explicit (PR labels like deploy:ecs) or deploy all variants always?

Would multiple labeling then work, deploy:ecs and deploy:eks, deploy both and not the default and would deploy run all three (or is there a deploy:* available to label?)

7. Should baselines be per-variant only, or also per-environment (dev baseline vs prd baseline)?

The baselines are per-variant against their main-<compute_variant>-prd match. Would this be a post post deployment asset or could this be looked at more like a release structure where the deploy.yml results in a release with a tag and cdk-*.out artifacts?? I kind of like this idea of main -> deploy.yml -> after successful build AND approval -> drafted release -> successful deployments -> tagged main and attached assets -> publish release

[bastizol-wq]

On “RFC: GitHub Actions CI/CD with protected deployment environment and approval gates”: you can get a lot of safety by doing a deterministic pre-flight before the agent calls the API.

If you already have OpenAPI/MCP metadata, you can make an allow/warn/block decision deterministically (and log it) before execution.

ATCP sits in front of tool execution: evaluate first, then decide whether the agent can call.

ATCP overview: https://www.sp-ai.io/atcp/

Curious what you’re using today for tool allowlists / safety receipts — happy to compare notes.

[scottschreckengaust]

On “RFC: GitHub Actions CI/CD with protected deployment environment and approval gates”: you can get a lot of safety by doing a deterministic pre-flight before the agent calls the API.

If you already have OpenAPI/MCP metadata, you can make an allow/warn/block decision deterministically (and log it) before execution.

ATCP sits in front of tool execution: evaluate first, then decide whether the agent can call.

ATCP overview: https://www.sp-ai.io/atcp/

Curious what you’re using today for tool allowlists / safety receipts — happy to compare notes.

Thank you for the consideration

[scottschreckengaust]

Addendum: github:* Resource Tagging Strategy

All stacks deployed via this pipeline (and locally) MUST carry the following tags on every taggable resource. Tags that cannot be resolved at synth time use sentinel value none — every stack always has the same tag schema.

Tag Schema

Tag key	CI source ($GITHUB_*)	Local fallback	Example
github:sha	$GITHUB_SHA	git rev-parse HEAD	f36d352c5a1bc3a90d3e60e30e2f9d4345426724
github:ref	$GITHUB_REF_NAME	git branch --show-current	main, v1.0.0
github:ref-type	$GITHUB_REF_TYPE	inferred	branch or tag
github:actor	$GITHUB_ACTOR	git config user.name	scottschreckengaust
github:head-ref	$GITHUB_HEAD_REF	none	PR source branch (PRs only)
github:run-id	$GITHUB_RUN_ID	none	12345678
github:event	$GITHUB_EVENT_NAME	local	push, pull_request
github:repository	$GITHUB_REPOSITORY	inferred from git remote	aws-samples/sample-autonomous-cloud-coding-agents
github:clean	true (CI is always clean)	git status --porcelain	true or false

Implementation

Tags are applied in cdk/src/main.ts via Tags.of(stack).add() using CDK context values (-c github:key=value). Empty values resolve to none to ensure consistent tag schema across all stacks.

Edge cases

Scenario	github:ref	github:head-ref	github:ref-type
Push to main	main	none	branch
PR #42 from feature/x	42/merge	feature/x	branch
Tagged commit v1.0.0	v1.0.0	none	tag
Local dev (no -c flags)	local	none	branch
Detached HEAD (local)	detached	none	branch

CLI invocation (local deploy)

npx cdk deploy \
  -c github:sha=$(git rev-parse HEAD) \
  -c github:ref=$(git branch --show-current || echo detached) \
  -c github:ref-type=branch \
  -c github:actor=$(git config user.name) \
  -c github:clean=$([ -z "$(git status --porcelain)" ] && echo true || echo false)

Limits

• CloudFormation allows 50 tags per resource (9 used here)
• aws: prefix is reserved; github: prefix avoids collision
• All tags are updatable on stack update — no replacement triggered
• Sentinel none avoids edge cases with empty string values in some AWS services

[scottschreckengaust]

Sub-issue created: #84 — Add github:* resource tagging strategy to CDK stacks (PR #85, draft)

[scottschreckengaust]

Findings: github:* Tag Schema vs. GitHub Trigger Events

Now that PR #85 has landed the 9-tag schema, here's an analysis of how the current tags behave (and where they break down) across the trigger types relevant to the deploy pipeline.

---

Current Tag Schema vs. GitHub Events

The core issue: github.sha and github.ref produce different semantics depending on the trigger, and two triggers (merge_group, pull_request) produce synthetic merge commits as github.sha that don't survive in git history after merge.

Tag	push	pull_request / pull_request_target	merge_group	workflow_dispatch
github:sha	actual commit SHA	synthetic merge commit (discarded post-merge)	merge group head SHA (synthetic, ephemeral)	HEAD of selected branch
github:ref	refs/heads/main	refs/pull/42/merge	refs/heads/gh-readonly-queue/main/pr-42-<hash> (opaque)	selected branch
github:ref-type	branch or tag	always PR ref (not useful)	ephemeral queue ref (not useful)	branch
github:actor	pusher	PR opener	PR author (queued by merge queue)	manual dispatcher
github:head-ref	empty → none	source branch (feature/x) ✓	not populated via $GITHUB_HEAD_REF → none	empty → none
github:run-id	✓	✓	✓	✓
github:event	push	pull_request	merge_group	workflow_dispatch
github:repository	✓	✓	✓	✓
github:clean	✓	✓	✓	✓

Legend: ✓ = works as expected, bold = produces a low-value or misleading value.

---

The merge_group Problem

When GitHub's merge queue fires, the context variables diverge significantly:

• github.sha → synthetic merge commit (doesn't exist in repo after queue completes)
• github.ref → refs/heads/gh-readonly-queue/main/pr-42-abc123 (opaque ephemeral branch)
• github.head_ref → empty (unlike pull_request, this isn't populated)

The useful values for merge queue live in the event payload:

• github.event.merge_group.head_sha — the real commit being tested
• github.event.merge_group.base_ref — target branch (e.g., main)
• github.event.merge_group.head_ref — the queue branch name

The current 'none' sentinel means the schema doesn't break — but resources tagged during a merge-queue deploy will have effectively useless github:sha and github:ref values that can't be traced back to a real commit.

---

Recommended Workflow Pattern: Conditional Tag Resolution

To produce meaningful tags regardless of trigger type, the deploy workflow should normalize context before passing to CDK:

- name: Resolve github:* tag values
  id: tags
  run: |
    case "${{ github.event_name }}" in
      merge_group)
        echo "sha=${{ github.event.merge_group.head_sha }}" >> $GITHUB_OUTPUT
        echo "ref=${{ github.event.merge_group.base_ref }}" >> $GITHUB_OUTPUT
        echo "ref-type=branch" >> $GITHUB_OUTPUT
        echo "head-ref=${{ github.event.merge_group.head_ref }}" >> $GITHUB_OUTPUT
        ;;
      pull_request|pull_request_target)
        echo "sha=${{ github.event.pull_request.head.sha }}" >> $GITHUB_OUTPUT
        echo "ref=${{ github.base_ref }}" >> $GITHUB_OUTPUT
        echo "ref-type=branch" >> $GITHUB_OUTPUT
        echo "head-ref=${{ github.head_ref }}" >> $GITHUB_OUTPUT
        ;;
      push)
        echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT
        echo "ref=${{ github.ref_name }}" >> $GITHUB_OUTPUT
        echo "ref-type=${{ github.ref_type }}" >> $GITHUB_OUTPUT
        echo "head-ref=" >> $GITHUB_OUTPUT
        ;;
      *)
        echo "sha=${{ github.sha }}" >> $GITHUB_OUTPUT
        echo "ref=${{ github.ref_name }}" >> $GITHUB_OUTPUT
        echo "ref-type=${{ github.ref_type }}" >> $GITHUB_OUTPUT
        echo "head-ref=" >> $GITHUB_OUTPUT
        ;;
    esac

- name: CDK Deploy
  run: |
    npx cdk deploy \
      -c github:sha=${{ steps.tags.outputs.sha }} \
      -c github:ref=${{ steps.tags.outputs.ref }} \
      -c github:ref-type=${{ steps.tags.outputs.ref-type }} \
      -c github:actor=${{ github.actor }} \
      -c github:head-ref=${{ steps.tags.outputs.head-ref }} \
      -c github:run-id=${{ github.run_id }} \
      -c github:event=${{ github.event_name }} \
      -c github:repository=${{ github.repository }} \
      -c github:clean=${{ steps.clean.outputs.clean }}

Key design choice: for pull_request and merge_group, we tag with the real PR head SHA (not the synthetic merge commit) because:

1. Synthetic merge commits are discarded after merge — you can't git show them later
2. The real SHA is what the developer pushed and what appears in the PR

---

Tags Worth Adding

These would close provenance gaps, especially for merge queue and multi-workflow scenarios:

Proposed Tag	Source	Rationale
github:base-ref	${{ github.base_ref }} / event.merge_group.base_ref	Distinguishes deployment target branch from source. Critical for merge_group and pull_request where github:ref is the source, not the target.
github:pr-number	${{ github.event.pull_request.number }} / extracted from merge group ref	Direct trace-back from deployed resource → PR. Simplifies cleanup queries (aws resourcegroupstaggingapi get-resources --tag-filters Key=github:pr-number).
github:run-attempt	${{ github.run_attempt }}	Distinguishes retries (same run-id, different attempt). Without this, redeployed resources from a retry look identical to the first attempt.
github:workflow	${{ github.workflow }}	If multiple workflows can deploy (e.g., deploy.yml vs hotfix.yml), identifies which produced this state.

Tag budget: CloudFormation allows 50 tags per resource. Current: 9 github:* + system tags (aws:*, Name). Adding 4 brings us to 13 custom — well within headroom.

Not recommended as tags (better in other metadata):

• github:trigger-sha (the synthetic merge SHA) — low value, can't be resolved post-merge; better to just not tag it
• github:merge-group-id — too ephemeral; the run-id + event=merge_group combination is sufficient for forensics

---

Updated Edge Cases Table (extending the addendum)

Scenario	github:sha	github:ref	github:head-ref	github:base-ref (proposed)	github:pr-number (proposed)
Push to main	commit SHA	main	none	none	none
PR #42 from feature/x	PR head SHA	main (target)	feature/x	main	42
Merge queue (PR #42)	PR head SHA (resolved)	main (base_ref)	queue branch	main	42 (extracted)
Tagged commit v1.0.0	commit SHA	v1.0.0	none	none	none
workflow_dispatch	HEAD SHA	selected branch	none	none	none
Local dev	git rev-parse HEAD	branch name	none	none	none

---

Action Items

1. Phase 2 item: When implementing deploy.yml, use the conditional resolution pattern above instead of passing raw $GITHUB_* env vars directly
2. Consider adding: github:base-ref and github:pr-number to the CDK tag schema (most impactful for cleanup/provenance)
3. Optional additions: github:run-attempt and github:workflow (lower priority, useful for multi-workflow setups)
4. No schema change needed for merge_group support — the workflow-level resolution handles it without modifying main.ts

cc @scottschreckengaust — these findings are from analyzing how PR #85's tag schema interacts with the trigger types planned in this RFC.