This repository contains a Terraform module for creating IAM Roles that can be assumed by GitHub Actions using web federation. Much of the work here is based off the excellent blog post by Aidan Steele.
PLEASE NOTE: This is as-of-yet (19th of September 2021) undocumented functionality, so this module should probably not be used in production environments as GitHub may change things before public release. See this GitHub Roadmap item for a current status of the feature.
This can be used in concert with this GitHub Action, which allows a workflow to assume a role. In fact, the tests that run as part of PR validation and release workflows for this very module use it!
For a full example of using the module, see my other repository here, where you can see a deployment for the OIDC provider and the IAM Role the workflows in this repository assume. (Please excuse the rather broad permissions assigned to the role; this is always run in a sandbox account that gets wiped frequently so the risk was minimal, though I do want to clean it up in the future.)
The module requires that you set up an OIDC provider for GitHub in your AWS Account prior to use, the ARN of which is required by the oidc_provider_arn
input variable. See below for an example Terraform resource that would provision this.
variable "github_repo_list" {
type = list(string)
description = "A list of GitHub orgs / users and repositories that the OIDC provider will trust. This must be in the format of 'org/repo'."
}
resource "aws_iam_openid_connect_provider" "github" {
url = "https://vstoken.actions.githubusercontent.com"
thumbprint_list = [ "a031c46782e6e6c662c2c87c76da9aa62ccabd8e" ]
client_id_list = formatlist("https://github.com/%s", var.github_repo_list)
}
The module deliberately does not include this resource in order to be flexible around how you deploy it. For example, some organizations may wish to keep all definitions of GitHub Action assumed roles in one, tightly controlled repository. In this case, the OIDC provider may well be deployed in the same set of code as the role(s) themelves. In other cases, repository owners themselves may be responsible for writing the deployments to manage their roles; in this case, the provider would have to be kept elsewhere, since there can be only one deployed per AWS Account.
Name | Version |
---|---|
aws | ~> 3.54 |
Name | Version |
---|---|
aws | ~> 3.54 |
No modules.
Name | Type |
---|---|
aws_iam_role.iam_role | resource |
aws_iam_role_policy_attachment.policy_attachment | resource |
aws_iam_policy_document.assume_role_policy | data source |
Name | Description | Type | Default | Required |
---|---|---|---|---|
github_branch_names | The names of the branches where actions running will be allowed to assume the role. This defaults to '*', which means that code running in any branch can assume the role. | list(string) |
[ |
no |
github_org_name | The name of the GitHub user or organization that owns the repository(ies) the role will use. | string |
n/a | yes |
github_repository_name | The name of the GitHub repository that will be allowed to assume the role. This defaults to '*', which will allow any repository within the org to assume the role. This is likely not a good use case for most deployments and may be changed in a future release. | string |
"*" |
no |
iam_policy_arns | A list of IAM Policy ARNs that should be attached to the created IAM Role. Can be not specified if policy attachments will be handled elsewhere. | list(string) |
[] |
no |
iam_role_boundary_policy_arn | If specified, the policy with the given ARN will be attached to the IAM Role as a boundary policy. If left as null (the default), no boundary policy will be attached. | string |
null |
no |
iam_role_name | The name of the IAM Role to be created. | string |
n/a | yes |
oidc_provider_arn | The ARN for the existing OIDC IAM provider for GitHub. | string |
n/a | yes |
Name | Description |
---|---|
assume_role_policy_json | The JSON result of the assume role policy document. This is mostly used for testing purposes. |
iam_role_arn | The ARN of the generated IAM Role. |