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

Compare commits

base: adam:5c362299de45038e8bccc46fd7e36e556d3650b5
Branches Tags
adam:main
adam:claude/dreamy-mccarthy-1c95cw
adam:fix/auto-merge-concurrency
...
compare: adam:6786d63291f32105c4207847335c9b2af810ce7d
Branches Tags
adam:main
adam:claude/dreamy-mccarthy-1c95cw
adam:fix/auto-merge-concurrency

2 commits
5c362299de ... 6786d63291

Author SHA1 Message Date
Adam Moussa
6786d63291
Merge pull request #23 from Sea-Haven-Industries/docs/fix-cd-sam-usage-example
Some checks are pending
ci / ci / ci (push) Waiting to run
Details 
docs(cicd): correct the cd-sam caller example to match the real contract
 2026-07-28 12:21:53 -04:00
Adam Moussa
065a4e9f0e
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 `<account-id>` placeholder, per the same rule
that removed the hardcoded management-account ARN from the templates.
 2026-07-28 12:16:37 -04:00
1 changed files with 14 additions and 1 deletions
Show stats 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: