From 065a4e9f0eb7722fec5dd26eec2729435b008956 Mon Sep 17 00:00:00 2001 From: Adam Moussa Date: Tue, 28 Jul 2026 12:12:17 -0400 Subject: [PATCH] docs(cicd): correct the cd-sam caller example to match the real contract The SAM deploy example passed `cfn-role-arn` as a secret and omitted `deploy-role-arn` entirely. Both are wrong against cd-sam.yaml, which declares `cfn-role-arn` as a required string INPUT and `deploy-role-arn` as a required SECRET. A repo scaffolded from the example failed twice: an unexpected secret, plus a missing required input and secret. The two ARNs are distinct roles that the old example effectively conflated into one, so document them side by side: cfn-role-arn is the CloudFormation execution role the stack deploys as, deploy-role-arn is the OIDC role the workflow assumes. Also record which inputs have defaults so callers pass only what they must. The account ID stays a `` placeholder, per the same rule that removed the hardcoded management-account ARN from the templates. --- cicd.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/cicd.md b/cicd.md index ed77d2b..90b48ed 100644 --- a/cicd.md +++ b/cicd.md @@ -67,10 +67,23 @@ jobs: uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@ # main with: stack-name: "your-stack-name" + cfn-role-arn: "arn:aws:iam:::role/github-cfn-execution-role" secrets: - cfn-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} + deploy-role-arn: ${{ secrets.AWS_DEPLOY_ROLE_ARN }} ``` +`cd-sam.yaml` takes two required inputs and one required secret. The two role ARNs are not interchangeable; they are different roles with different jobs: + +| Name | Kind | Purpose | +|---|---|---| +| `stack-name` | input (`with:`) | The CloudFormation stack name | +| `cfn-role-arn` | input (`with:`) | The **CloudFormation execution role** the stack is deployed *as*. This is `github-cfn-execution-role` in the repo's target account. Substitute that account's ID for ``; the account must have the deploy substrate provisioned before the first deploy. Do not point new repos at the management account. | +| `deploy-role-arn` | secret (`secrets:`) | The **OIDC role the workflow assumes**, from the repo's `AWS_DEPLOY_ROLE_ARN` secret (see [Authentication](#authentication)) | + +Passing `cfn-role-arn` under `secrets:` fails: it is an input, so the run errors on an unexpected secret *and* a missing required input. + +The remaining inputs have defaults and are only needed when a repo differs from them: `region` (`us-east-1`), `sam-template` (`template.yaml`), and `python-version` (`3.12`). The optional `parameter-overrides` secret passes `Key=Value` pairs through to `sam deploy`. + ## Authentication Deploy workflows authenticate to AWS via OIDC (no long-lived credentials). Each repo needs: