Skip to content

Latest commit

 

History

History
82 lines (65 loc) · 6.08 KB

README.md

File metadata and controls

82 lines (65 loc) · 6.08 KB

github-oidc

Terraform module that provisions the AWS IAM OIDC provider for GitHub Actions and an IAM role for terraform plan/apply runs.

Inputs

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)

Outputs

Name Description
role_arn ARN of the IAM role used by GitHub Actions
provider_arn ARN of the IAM OIDC provider

Bootstrap

  1. Run the first apply locally with temporary admin credentials so Terraform can create the OIDC provider and IAM role.
  2. Retrieve the role ARN from terraform state show module.github_oidc.aws_iam_role.github_actions and save it into the GitHub repository variable AWS_TERRAFORM_ROLE_ARN.
  3. Save the deployment region into the repository variable AWS_REGION.
  4. Configure GitHub environments staging and production with required reviewers before enabling terraform-apply.yml.

Notes

  • The trust policy is locked to refs/heads/main plus the staging and production GitHub environments.

  • Object read/write is limited to the env/staging/* and env/production/* prefixes used by the workflow; env/dev/* objects are not readable or writable by the CI role. s3:ListBucket is bucket-wide, so the role can see other environments' state key names, sizes and timestamps. Narrowing s3:ListBucket with an s3:prefix condition 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_ARN is unset; the scope described here is what the tracked configuration would produce. The workflow reads exactly one AWS_TERRAFORM_ROLE_ARN repository variable for both workflow_dispatch environments, so a single role serves both. Because that role is shared, it holds s3:PutObject/s3:DeleteObject on every environment listed in state_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_actions is 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 with EntityAlreadyExists; that state must first import the existing provider. terraform import loads the configuration, so it needs both the production backend key and the root variables (environment, vpc_id and private_subnet_ids have 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 only aws_iam_openid_connect_provider. A production apply also creates agentflow-terraform-production plus its own -boundary policy, and AWS_TERRAFORM_ROLE_ARN must 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 for token.actions.githubusercontent.com on 2026-04-22. Rotate it if the top intermediate CA changes.

State locking

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.

Provider lock

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