docs: OIDC-preferred + GitHub App token recommendations (Phases 2 + 3)#25
Merged
Merged
Conversation
Closes #8 and #9. Documentation-only; no code change. ## Phase 2 (#8) — OIDC for AWS credentials README's 'How to start' step 1 now leads with GitHub OIDC as the preferred path and relegates static IAM access keys to a 'legacy' Option B. Rationale: static keys don't rotate, live in GitHub secrets indefinitely (permanent attack surface), and can't be scoped to a specific repo/branch/environment. OIDC issues short-lived STS tokens per run, scoped by repo/branch/environment. Includes: - A Terraform example for the trust-relationship IAM role with a repo-scoped 'sub' StringLike condition. - The minimum permissions policy (unchanged — attaches to role or user). - A workflow snippet showing 'permissions: id-token: write' and 'role-to-assume' instead of access-key secrets. No changes to the action's code — it already reads AWS creds from env, which configure-aws-credentials@v6 populates identically under both paths. ## Phase 3 (#9) — GitHub token type preferences README's 'How to start' step 2 replaced. Three token options ordered by preference: - A (preferred): GitHub App installation token via actions/create-github-app-token. No human identity, short-lived, minimal permission (Repository Administration: read/write). - B: fine-grained PAT scoped to specific repos with just Repository Administration. Better than classic PAT but still tied to a human. - C (deprecated): classic PAT with 'repo' scope. Over-permissive and human-tied; kept in docs as a fallback for environments that don't allow Apps or fine-grained PATs. No code change — the action accepts any token that has permission to manage self-hosted runners on the target repo. Docs change only. ## Not included in this PR - Phase 2's optional 'role-to-assume' input on the action itself (so consumers don't need the separate configure-aws-credentials step). Deferred — the current dual-step pattern is standard and works fine. Convenience feature, not urgency. Signed-off-by: yuriyryabikov <22548029+kurok@users.noreply.github.com>
This was referenced Apr 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #8 and #9. Documentation-only — no code change.
Phase 2 (#8)
README's 'How to start' step 1 now leads with GitHub OIDC as the preferred AWS credential path. Static access keys become Option B, explicitly labelled legacy. Includes Terraform for the trust role (with repo-scoped
subcondition), the unchanged least-privilege permissions policy, and a workflow snippet showingpermissions: id-token: write+role-to-assume.The action's code needs no change — it reads AWS creds from env, which
aws-actions/configure-aws-credentials@v6populates identically under both paths.Phase 3 (#9)
README's 'How to start' step 2 replaced. Three token options ranked by preference:
reposcope (over-broad)The action accepts any token with permission to manage self-hosted runners on the target repo — the change is purely in the README's guidance.
Not included here
role-to-assumeinput on the action itself (so consumers skip the separateconfigure-aws-credentialsstep). Deferred — the current dual-step pattern is standard and documented everywhere. Convenience feature, not a blocker.docs/github-app.mdend-to-end App setup walkthrough. The README section points at the upstream docs; standalone walkthrough is nice-to-have but not part of Phase 3: recommend GitHub App token / fine-grained PAT over classic PAT #9's acceptance criteria.Test plan
unit-testsjob is orthogonal to docs).