CCHQ ARTICLE GUIDE / DEVOPS & AUTOMATION
Practical learning, clear decisions, real-world context
An easy-to-navigate field guide with key takeaways, applied checks, FAQs, and official references. Approximately 7 minutes of reading.
Quick answer: Connecting GitHub Actions to AWS with OIDC lets approved workflows assume short-lived IAM role credentials without storing long-lived AWS access keys.
GitHub Actions can deploy to AWS without storing a long-lived AWS access key in repository secrets.
The recommended pattern uses OpenID Connect (OIDC): GitHub issues a short-lived identity token to an authorized workflow, and AWS Security Token Service exchanges it for temporary credentials when a tightly scoped IAM role trust policy allows the request.
This reduces one important secret-management risk, but it does not automatically make a pipeline safe. A trust policy that permits every repository or branch to assume a production role can still create serious exposure.
This guide explains the identity flow, the required configuration, an illustrative workflow, the security controls around pull requests and environments, and a practical way to confirm that the deployment role cannot access resources outside its job.
At a glance
The main topics you’ll work through:
- How GitHub OIDC and AWS STS work
- Create an IAM OIDC identity provider
- Write a restrictive role trust policy
- Grant the least deployment permissions
In this guide
ARCHITECTURE AT A GLANCE
GitHub Actions to AWS using OIDC
01
Approved GitHub workflow
02
Short-lived OIDC token
03
AWS STS role assumption
04
Scoped AWS API access
The IAM role trust policy and role permissions provide separate checks.
01 / KEY CONCEPT
How GitHub OIDC and AWS STS work
KEY TAKEAWAY
A workflow with appropriate permissions requests an identity token from GitHub’s OIDC provider.
The token includes claims identifying its issuer, audience, and workload context, such as repository and reference information. AWS evaluates these claims against an IAM role trust policy configured to recognize GitHub as an identity provider.
When the request passes the trust conditions, AWS STS provides temporary role credentials. The workflow then calls AWS APIs through those credentials. No static AWS key needs to live in GitHub Secrets.
Temporary credentials improve rotation and reduce persistence, but they remain powerful while valid. The role permissions determine which AWS operations the job can perform, and the trust policy determines which workflow contexts may obtain the role.
Think of those as separate security layers. A successful role assumption does not mean the job should receive administrator access.
The best design explicitly separates test deployments from production, and ensures that untrusted code cannot silently run with privileged credentials.
02 / PRACTICAL APPLICATION
Create an IAM OIDC identity provider
KEY TAKEAWAY
In the AWS account that will receive deployments, configure an IAM OIDC identity provider for GitHub’s token issuer and the AWS STS audience.
Follow the current GitHub and AWS instructions for the exact provider URL and audience value instead of copying unverified thumbprints or console screenshots. Create a dedicated role for the workflow.
Its trust policy should accept tokens from that provider only under documented conditions. Don’t confuse the identity provider with the role or the permissions policy attached to the role.
Plan the repository and environment scope before writing conditions. A production deployment from a protected GitHub environment should use a different trust boundary from a general branch build.
Verify the organization name, repository name, and branch or environment syntax exactly. Wildcard conditions that accept every repository can turn an unrelated GitHub project into an entry point for your AWS account.
If multiple repositories require access, use distinct roles or carefully justified and reviewed conditions, depending on ownership and risk.
03 / KEY CONCEPT
Write a restrictive role trust policy
KEY TAKEAWAY
A common GitHub-to-AWS trust design checks the OIDC token audience and subject.
For a branch-restricted deployment, the subject can identify an organization, repository, and branch. For an environment-restricted deployment, the subject format may identify the GitHub environment instead.
The trust policy must match how the actual workflow requests the token. AWS and GitHub documentation describe the conditions necessary to prevent unrelated repositories from assuming the role.
Treat trust-policy changes as sensitive infrastructure modifications. Review them with another engineer and test both an allowed workflow and a disallowed workflow.
Avoid broad patterns introduced to resolve a failing build without understanding why the claim differs from your expectation. If a branch was renamed or an environment protection rule changed, update the policy deliberately.
An OIDC migration is a good opportunity to remove obsolete access keys, but revoke them only after the new workflow succeeds under its intended constraints.
04 / PRACTICAL APPLICATION
Grant the least deployment permissions
KEY TAKEAWAY
Attach a separate permissions policy listing only the actions necessary for the deployment.
A website upload role might need constrained S3 write permissions for a content prefix and perhaps cache invalidation for one distribution.
A Terraform deployment role may need broader infrastructure operations, but should still be bounded by service, resource, account, environment, and organization guardrails wherever feasible. Do not use an AdministratorAccess policy as a long-term shortcut.
Consider deployment ownership carefully. A CI job that can change IAM roles may effectively escalate access even if it starts with a narrow-looking policy. Separate build and infrastructure administration roles where practical.
Use permissions boundaries and service control policies for additional organizational safeguards. Inspect the specific deployment actions generated by Terraform or the chosen tool before granting them.
A failure caused by a missing permission is an opportunity to refine a role from evidence, not to give the job unrestricted access.
05 / KEY CONCEPT
Configure the GitHub Actions workflow
KEY TAKEAWAY
The job must have permission to request an OIDC token.
In GitHub Actions, permissions: id-token: write allows token requests, while contents: read is commonly enough to fetch source.
Use the maintained aws-actions/configure-aws-credentials action to assume the configured role, specifying an approved region and role ARN.
Pin actions according to your organization’s dependency-management policy and review the action’s current documentation for supported inputs.
An illustrative pipeline has separate jobs for formatting and tests, plan creation, approval, and production deployment. Restrict the privileged job to an approved branch or protected environment and give it only the credentials it needs.
The build job should not inherit the production role. Limit third-party actions and carefully review shell steps that interpolate user-controlled values. Avoid printing OIDC tokens, temporary credentials, Terraform state, or secret variables in the job output.
A readable audit log is more valuable than a verbose log containing private data.
06 / PRACTICAL APPLICATION
Protect pull requests and environments
KEY TAKEAWAY
A pull request from a fork or an untrusted contributor should never be able to modify the trusted deployment workflow and immediately obtain production credentials.
Review GitHub event triggers, token permissions, branch protections, environment reviewers, and which jobs can execute unreviewed code.
The pull_request_target event has special security considerations because it executes in a privileged context; do not casually combine it with checkout of untrusted contribution code.
Use separate environments for development and production. GitHub environment protection rules can require approvals and restrict deployment branches, but the AWS trust policy must also match the intended environment subject.
Relying on GitHub settings alone while leaving a broad AWS trust condition creates a second path that may be exploitable. Check repository and organization administrator access as part of the threat model.
An attacker able to rewrite protected workflows can often bypass assumptions that seemed safe at the start of the project.
07 / KEY CONCEPT
Validate identity and denied access
KEY TAKEAWAY
Begin with a nonproduction environment.
Run an approved workflow and use aws sts get-caller-identity within it to confirm the assumed role and account, taking care not to print tokens or secrets. Then run a harmless action the deployment role should be allowed to perform.
Confirm a similarly harmless request outside its scope is denied. Compare the result to the IAM policy and trust conditions. If the action fails, inspect the claim context, ARN, and policy evaluation rather than adding a wildcard grant.
Test a disallowed branch or repository context when you can do so safely, without attempting to bypass organizational controls. Verify the role cannot be assumed outside the approved subject.
Review CloudTrail role-assumption events and relevant deployment logs, recognizing that event visibility depends on configuration. Rotate or revoke legacy credentials after the new system is validated.
Keep a change record with what the workflow deployed, who approved it, which role was used, and how to restore service if the deployment caused a regression.
08 / PRACTICAL APPLICATION
Operational limits, costs, and rollback
KEY TAKEAWAY
OIDC itself does not remove AWS compute, storage, deployment, or logging charges.
A pipeline might provision billable infrastructure even if the build job is inexpensive. Set budget alerts and use a deliberate teardown workflow for temporary environments. Consider concurrency controls so two deployments cannot alter shared resources at once.
For Terraform, enable appropriate state locking and protect saved plans. For application releases, consider versioned artifacts and health checks so you can recover from a bad change.
An approval gate can stop a dangerous deployment, but it cannot automatically reverse an applied data migration or deleted resource. Document recovery limits, backup assumptions, and ownership before enabling scheduled production applies.
Observe the application after release, not only the workflow status. A green GitHub job means the automation exited successfully; it does not establish that the application is available, secure, or meeting user expectations.
Pair automation with direct service validation and alerting.
Before you finish: practical checklist
Turn the main lessons into a short review of your own environment:
- Plan the repository and environment scope before writing conditions.
- Verify the organization name, repository name, and branch or environment syntax exactly.
- Review them with another engineer and test both an allowed workflow and a disallowed workflow.
- Avoid broad patterns introduced to resolve a failing build without understanding why the claim differs from your expectation.
- Use permissions boundaries and service control policies for additional organizational safeguards.
Command quick reference
Use these commands only in an appropriate, authorized environment, after checking prerequisites.
aws sts get-caller-identityFrequently asked questions
Do I still need GitHub Secrets?
You do not need long-lived AWS access keys for the OIDC role-assumption path. Other application secrets may still require protected storage and controlled access.
Does id-token: write provide AWS permissions?
No. It allows requesting an OIDC token. AWS trust and permission policies decide whether the job may assume a role and which API calls that role can make.
Why does role assumption fail on a protected environment?
Check that the token subject matches the environment rather than the branch format, and review environment approval and trust-policy conditions. Confirm against current provider documentation.
Authoritative references and next step
GitHub OIDC to AWS configuration · AWS IAM best practices · Terraform state locking
Start with a small read-only or constrained development role, then validate both an allowed workflow and a denied context before deploying to production.
Continue with DevOps & Automation for IaC workflow and change-review patterns.
