feat(ci): add deploy pipeline with OIDC, dynamic stack naming, and deploy-intent artifact

[scottschreckengaust]

Summary

Adds the deployment pipeline (Phase 3 of #73) on top of PR #97 (compute_type rename).

Architecture

build.yml (single entry point for build + deploy intent)
  ├─ workflow_dispatch input: deploy = "-" (default) | "agentcore"
  │   └─ GitHub enforces choice values — no injection possible
  ├─ Resolve stack name (trigger-aware, sanitized)
  ├─ Generate cdk.context.json (stackName + compute_type + github:* tags)
  ├─ mise run build → synth → upload cdk-<type>-out artifact
  ├─ Write deploy-intent.json (validated against ALLOWED_COMPUTE_TYPES)
  └─ Upload deploy-intent artifact

deploy.yml (pure consumer — no direct triggers)
  ├─ workflow_run: fires after build succeeds
  ├─ resolve-targets: download deploy-intent.json
  │   ├─ intent = "-"      → skip (no approval prompt, instant no-op)
  │   ├─ intent = "labels" → check PR labels, validate against allowlist
  │   └─ intent = "<type>" → validate against allowlist, deploy
  └─ deploy job:
      ├─ environment: deploy (manual approval, prevent self-review)
      ├─ cancel-in-progress: false (non-cancellable once started)
      ├─ max-parallel: 3
      ├─ download exact cdk-<type>-out artifact from build run
      ├─ OIDC → CDK bootstrap role
      └─ npx cdk deploy --app cdk/cdk.out --all --require-approval never

Commits

#	Commit	Description
1	compute_type rename	computeVariant → compute_type in build.yml, context, CDK tag (from PR #97)
2	deploy.yml base	workflow_run trigger, artifact download, OIDC, cdk deploy
3	Dynamic stack naming	Trigger-aware naming with sanitization
4	Deploy-intent pattern	Move dispatch input to build.yml, deploy.yml becomes pure consumer
5	Security hardening	Allowlist validation, jq for JSON, numeric PR check, letter-prefix stacks

Stack Naming

Trigger	Pattern	Example
Push to main	main-<type>	main-agentcore
Push to branch	<branch>-<type>	feat-deploy-yml-agentcore
Pull request	pr<N>-<type>	pr42-agentcore
Merge group	mg<N>-<type>	mg42-agentcore
workflow_dispatch	<branch>-<type>	main-agentcore
Fallback	<type>-<sha7>	agentcore-abc1234

Sanitization: lowercase, /_. → -, strip non-[a-z0-9-], collapse hyphens, 60-char cap, prefix s- if starts with digit.

Deploy Intent Flow

Build trigger	Intent value	Deploy result
Push to main	agentcore	Deploy agentcore
Push to non-main branch	-	No deploy
workflow_dispatch with -	-	No deploy
workflow_dispatch with agentcore	agentcore	Deploy agentcore
pull_request	labels	Check PR labels
Unknown	-	No deploy

Label-Driven Deploy (PR only)

Label	Types deployed
deploy	All registered types
deploy:agentcore	agentcore only
deploy:*	All registered types
No deploy* label	Nothing

Label values are validated against ALLOWED_COMPUTE_TYPES. Invalid labels emit a warning and are silently dropped.

Depends on: PR #97 — must merge first.

Security

Control	Location	Mechanism
Input validation	build.yml dispatch	GitHub choice type — enforced at UI and API
Compute type allowlist	Both workflows	ALLOWED_COMPUTE_TYPES env var; validate_compute_type()
Label filtering	deploy.yml	filter_valid_types() rejects invalid deploy:<type> labels
PR number validation	build.yml naming	Regex ^[0-9]+$ check before use
Stack name sanitization	build.yml naming	Lowercase, strip unsafe chars, letter-prefix, 60-char cap
JSON encoding	build.yml intent	jq -n --arg (not shell interpolation)
No expression injection	Both workflows	All untrusted input via env:, never in run: directly
Permissions	Both workflows	permissions: {} at top; least-privilege per job
OIDC	deploy.yml	No long-lived credentials; assumes CDK bootstrap roles
Environment gate	deploy.yml	deploy environment with manual approval, prevent self-review
Non-cancellable deploys	deploy.yml	cancel-in-progress: false once deployment starts
zizmor	Both workflows	Passes with 1 documented intentional suppression

Test plan

• YAML validates on both files
• zizmor passes on both files (0 findings, 1 ignored, 8 suppressed)
• Pre-commit hooks pass (eslint, gitleaks, yaml check)
• github-tags.test.ts — 5/5 pass (compute_type tag defaults + explicit)
• TypeScript compiles clean
• End-to-end: workflow_dispatch build with deploy: agentcore
• End-to-end: PR with deploy label
• Verify stack naming for each trigger type
• Verify invalid deploy:foo label emits warning and is ignored

Not in scope (future work)

• Baseline diff step (download from latest release, compare resource types)
• cdk diff output to step summary
• Release flow (draft → deploy → tag → publish)
• Cleanup workflow (cleanup.yml)

🤖 Generated with Claude Code

[krokoko]

Review summary

Thanks for this — the architecture is sound and the security framing is genuinely strong (SHA-pinned actions, env-var-only untrusted input, deny-by-default permissions, OIDC, approval gate, synth-once/deploy-exact-artifact). It aligns cleanly with the Phase 3 goals in #73. A few items I'd like to see addressed before merge, none requiring a redesign.

🔴 Blocking

B1 — filter_valid_types emits multi-line JSON, corrupting the matrix output (deploy:<type> path is broken). deploy.yml:55

valid_json=$(echo "$valid_json" | jq --arg t "$type" '. + [$t]')   # missing -c

VALIDATED becomes pretty-printed multi-line JSON, then deploy.yml:88 does echo "matrix=$VALIDATED" >> "$GITHUB_OUTPUT". GitHub Actions parses one key=value per line, so matrix captures only [ and fromJson(...outputs.matrix) in the deploy job fails — the deploy:agentcore-style label path never deploys. (The COUNT check on line 86 masks it because jq 'length' tolerates multi-line input.)
Fix: jq -c --arg t "$type" '. + [$t]', and add a CI test exercising a deploy:agentcore label since this path has no coverage today.

B2 — Deploy job runs a PR-synthesized cloud assembly with --require-approval never; manual approval is the only defense against malicious CloudFormation. deploy.yml:166 (+ fork guard at deploy.yml:12-14)
build.yml runs on pull_request (untrusted PR-head code), cdk synth produces the cdk-<type>-out artifact, and deploy.yml downloads that exact artifact and runs npx cdk deploy --app cdk/cdk.out --all --require-approval never. The head_repository.full_name == github.repository guard blocks forks but not same-repo branch PRs — any contributor who can push a branch could author a PR whose synth emits arbitrary CloudFormation (e.g. an over-broad IAM role), and a human approving the deploy environment is reviewing an opaque generated template rather than the diff.
Fix (pick one): (a) restrict the deploy path to push-to-main/merged intent and drop PR-label deploys; or (b) re-synthesize from the checked-out trusted ref inside the deploy job rather than trusting the uploaded cdk.out; or (c) at minimum drop --require-approval never and surface a cdk diff in the step summary for the approver. (The RFC's Phase 3 checklist already lists the cdk diff step as unchecked — that's exactly the compensating control here.)

B3 — Stack-name sanitize() can produce CloudFormation-invalid names. build.yml:134-138

• cut -c1-60 runs after the trailing-hyphen trim, so a hyphen at position 60 survives → trailing hyphen.
• An all-special-char ref sanitizes to empty → STACK_NAME="-agentcore". The guard only checks ^[0-9], so a leading hyphen isn't caught and CloudFormation rejects it (names must start with a letter). Affects the push / workflow_dispatch paths only.

Fix:

result=$(... | cut -c1-60 | sed 's/-$//')
if [[ ! "$result" =~ ^[a-z] ]]; then result="s-${result}"; fi

🟡 Non-blocking

• index("deploy:*") is a literal match, not a glob (deploy.yml:80). It only matches a label named exactly deploy:*; the bare deploy branch already means "all types." This branch is dead/misleading and is a surprise full-deploy vector if such a label is ever created — remove it or rename to an explicit deploy:all sentinel.
• PR_NUMBER_FROM_EVENT from workflow_run.pull_requests[0].number (deploy.yml:36) is empty for forks and often for same-repo indirect runs. It fails safe (no deploy), so no security issue, but a label-driven deploy may silently no-op — worth documenting or resolving via gh api on head_sha.
• ALLOWED_COMPUTE_TYPES is duplicated across both workflows plus the matrix; drift silently disables a type. A follow-up to source it from one place would be nice.
• exit 1 vs return 1 between build.yml and deploy.yml is correct in both cases — a one-line comment explaining why they differ would help future maintainers.

📄 Docs

Nicely done — DEPLOYMENT_GUIDE.md and its Starlight mirror were both regenerated in the same diff, so the mutation check passes. One thing: the ROADMAP wasn't touched — if this completes/advances a CI/CD item there, please update docs/guides/ROADMAP.md and re-run mise //docs:sync.

✅ Tests & CI

All checks green. Main gap is that the new bash logic (sanitize, intent resolution, label filtering) has no test coverage — B1 is exactly the kind of bug one end-to-end deploy:agentcore test would have caught. The PR's own test plan leaves the four end-to-end items unchecked.

Governance notes (per ADR-003)

• Branch feat/deploy-yml doesn't follow feat/<issue-number>-short-description (e.g. feat/73-deploy-pipeline) — the issue is linked in the PR body, just flagging the convention.
• Issue RFC: GitHub Actions CI/CD with protected deployment environment and approval gates #73 carries enhancement but not the approved label. As Phase 3 of an RFC with merged predecessors (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) the work is clearly sanctioned, but worth confirming the approved gate with an admin before merge.

---

Bottom line: B1 is a one-character fix that unblocks the label path, B2 is the trust gap worth closing (at least cdk diff + dropping --require-approval never), and B3 covers two name-sanitization edge cases. With those addressed this is a solid, well-secured pipeline. 🚀

Reviewed as Principal Architect; security + shell-logic analysis run by specialized review agents.

[scottschreckengaust]

**B1

Will fix

**B2 (c) at minimum drop --require-approval never and surface a cdk diff in the step summary for the approver. (The RFC's Phase 3 checklist already lists the cdk diff step as unchecked — that's exactly the compensating control here.)

But without the --require-approval never the CI/CD process will not deploy, the other (a) and (b) options do not accomplish the needs. Would that suffice (including the ability to review the cdk diff before approval)?

**B3

Yes

[scottschreckengaust]

Re: Governance notes

• Branch naming: Acknowledged that feat/deploy-yml doesn't follow the feat/<issue-number>-short-description convention. Renaming at this point would disrupt the open PR and existing CI runs — accepting the deviation for this PR rather than force-pushing a branch rename.
• approved label: Confirmed added to RFC: GitHub Actions CI/CD with protected deployment environment and approval gates #73. ✅

[scottschreckengaust]

Review follow-up — status of all items

Branch rebased onto latest main (includes PR #217 TMPDIR fix).

Blocking

Item	Status
B1 — filter_valid_types multi-line JSON	✅ Fixed (jq -c)
B2 — PR-synthesized artifact trust gap	⏳ Pending design decision (options a/b/c from review)
B3 — sanitize() edge cases	✅ Fixed (reorder cut/trim, guard empty + leading non-letter)

Non-blocking

Item	Status
deploy:* dead literal match	✅ Removed
ALLOWED_COMPUTE_TYPES duplication	✅ ALL_TYPES derived dynamically; cross-reference comments added
exit 1 vs return 1	✅ One-line comments explaining the design choice in each workflow
PR_NUMBER_FROM_EVENT empty for forks	✅ Fallback via gh api commits/{sha}/pulls with warning on failure

Docs / Governance

Item	Status
ROADMAP update	Not needed — the deploy workflow is internal CI/CD tooling, not a user-facing platform capability tracked in the roadmap
Branch naming	Acknowledged (not renaming — would disrupt open PR)
approved label on #73	✅ Added

---

All code-actionable items from the review are addressed. Only B2 remains as a design decision.