adam/engineering-handbook
1
0
Fork 0
mirror of https://github.com/Sea-Haven-Industries/engineering-handbook.git synced 2026-09-30 06:53:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(cicd): correct the cd-sam caller example to match the real contract

Browse source 
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 `<account-id>` placeholder, per the same rule
that removed the hardcoded management-account ARN from the templates.
This commit is contained in:
Adam Moussa 2026-07-28 12:12:17 -04:00
parent 5c362299de
commit 065a4e9f0e
No known key found for this signature in database
1 changed files with 14 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
cicd.md
View file

@ -67,10 +67,23 @@ jobs:
uses: Sea-Haven-Industries/.github/.github/workflows/cd-sam.yaml@<full-commit-sha> # main
with:
stack-name: "your-stack-name"
cfn-role-arn: "arn:aws:iam::<account-id>: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 `<account-id>`; 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: