Terraform module that provisions the AWS IAM OIDC provider for GitHub Actions and an IAM role for terraform plan/apply runs.
| Name | Description | Type |
|---|---|---|
github_org |
GitHub organization or user that owns the repository | string |
github_repo |
Repository name allowed to assume the role | string |
role_name |
IAM role name for GitHub Actions Terraform runs | string |
allowed_branches |
Branch refs allowed in the OIDC sub claim |
list(string) |
allowed_environments |
GitHub environments allowed in the OIDC sub claim |
list(string) |
state_environments |
Environment names whose env/<name>/* state keys the role may access |
list(string) |
| Name | Description |
|---|---|
role_arn |
ARN of the IAM role used by GitHub Actions |
provider_arn |
ARN of the IAM OIDC provider |
- Run the first apply locally with temporary admin credentials so Terraform can create the OIDC provider and IAM role.
- Retrieve the role ARN from
terraform state show module.github_oidc.aws_iam_role.github_actionsand save it into the GitHub repository variableAWS_TERRAFORM_ROLE_ARN. - Save the deployment region into the repository variable
AWS_REGION. - Configure GitHub environments
stagingandproductionwith required reviewers before enablingterraform-apply.yml.
-
The trust policy is locked to
refs/heads/mainplus thestagingandproductionGitHub environments. -
Object read/write is limited to the
env/staging/*andenv/production/*prefixes used by the workflow;env/dev/*objects are not readable or writable by the CI role.s3:ListBucketis bucket-wide, so the role can see other environments' state key names, sizes and timestamps. Narrowings3:ListBucketwith ans3:prefixcondition is a follow-up that needs verification against a real backend init. -
No bootstrap apply has been performed, so no role exists yet and
AWS_TERRAFORM_ROLE_ARNis unset; the scope described here is what the tracked configuration would produce. The workflow reads exactly oneAWS_TERRAFORM_ROLE_ARNrepository variable for bothworkflow_dispatchenvironments, so a single role serves both. Because that role is shared, it holdss3:PutObject/s3:DeleteObjecton every environment listed instate_environments, so the per-environment state keys separate state objects, not credentials. A per-environment role would need a per-environment role variable in the workflow, which this repository does not have. -
aws_iam_openid_connect_provider.github_actionsis account-global and is owned by the state the bootstrap was run from (env/staging/terraform.tfstate). A second environment applied from an empty state would fail withEntityAlreadyExists; that state must first import the existing provider.terraform importloads the configuration, so it needs both the production backend key and the root variables (environment,vpc_idandprivate_subnet_idshave no defaults):terraform init -reconfigure -backend-config="key=env/production/terraform.tfstate" terraform import -var-file=environments/prod.tfvars \ module.github_oidc.aws_iam_openid_connect_provider.github_actions \ arn:aws:iam::<account-id>:oidc-provider/token.actions.githubusercontent.com
Run it from a working directory inited against the production key; an operator who has just bootstrapped is inited against
env/staging/terraform.tfstate, where the provider is already managed. The import covers onlyaws_iam_openid_connect_provider. A production apply also createsagentflow-terraform-productionplus its own-boundarypolicy, andAWS_TERRAFORM_ROLE_ARNmust continue to name the single role the workflows use — the operator decides which of the two ARNs that variable keeps. Full procedure:docs/operations/aws-oidc-setup.md. -
The inline policy is intentionally action-scoped instead of using broad admin policies. Some AWS APIs still require
Resource = "*"for create/list operations. -
The checked-in thumbprint is
dd55b4520291e276588f0dd02fafd83a7368e0fa, observed fortoken.actions.githubusercontent.comon 2026-04-22. Rotate it if the top intermediate CA changes.
The S3 backend in infrastructure/terraform/main.tf keeps
dynamodb_table = "agentflow-terraform-locks" on purpose, together with the
TerraformStateLockTableDescribe / TerraformStateLockItems statements and
the dynamodb:LeadingKeys condition in this module. The parameter is
deprecated as of Terraform 1.15.4 and terraform init emits
Warning: Deprecated Parameter. The replacement is S3 native locking
(use_lockfile = true). Migration is deferred because it changes the
locking mechanism of a live backend and needs AWS access plus a
lock-migration step. Revisit on the next Terraform major bump, or the first
time the backend is recreated from scratch — whichever comes first.
The executable plan for that day — preconditions, the dual-lock step order, the
IAM statements to remove and when, and the rollback — is in
docs/operations/aws-oidc-setup.md
under State locking. It is not duplicated here.
infrastructure/terraform/.terraform.lock.hcl is generated by Terraform, not
hand-edited. After an AWS provider version bump, regenerate hashes for the
platforms this repository actually runs (ubuntu-latest CI, macOS verification
host, local Windows) from infrastructure/terraform. The tracked lock file's
h1: hashes do not label platforms. Coverage of linux_amd64 for
ubuntu-latest is guarded by .github/workflows/ci.yml terraform-validate,
which runs terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 -platform=windows_amd64 in infrastructure/terraform/ and fails on a
non-empty git diff --exit-code .terraform.lock.hcl. That step is a tracked
guard, not observed runner evidence. The same invocation also records
darwin_arm64 and windows_amd64. Regenerate locally with this command:
terraform providers lock -platform=linux_amd64 -platform=darwin_arm64 -platform=windows_amd64