Configuring GitHub Actions to deploy on AWS using OpenID Connect (OIDC)
GitHub Actions has become one of the popular choices for CI/CD systems since its roll out a few years ago. It is easy to use and has predefined and managed runners for Linux, Windows and MacOS. It also has the option to configure your own runners if a specific hardware configuration or OS is desired.
From my experience, I noticed that build times are slightly shorter than other CI systems that I used in conjunction with GitHub. Also, the integration comes out of the box since there is no GitHub WebHook integration with external systems involved in this.
Implementation
This post shows how to create a role which can be used in your repositories to deploy to AWS directly from GitHub Actions.
The implementation of this role is done using terraform.
Prerequisites
- AWS CLI configured with credentials with privileges to create a IAM role, typically Admin
You may choose to use one of the existing users but I highly recommend to create a dedicated user only with only programmatic access (no console access) and attach the necessary permissions. That is what I have done. - Terraform CLI
- Any terminal of your choice. Powershell, GitBash etc
Before the OIDC approach to use GitHub Actions with AWS, the user credentials such as Access Key ID and Secret Access Key had to be stored within each application repository to enable deploying to AWS.
In most real life applications, handling of such credentials is only done by Administrators and DevOps engineers. Thus, creating these secrets for each repository every time a new GitHub Repository is created could be an additional overhead for them and also not a very secure practice.
Using the OIDC approach we are effectively creating a role and GitHub Actions assumes this role temporarily and then deploys to AWS. As a DevOps Engineer or Admin, you only need to give out the of ARN of this role to your developers with some instructions on how to use it in their workflows.
Before creating this role, the identity provider should be created. This can be easily done using the console.
On your IAM home page, go to Identity providers. Choose OpenID Connect. Input the provider URL as `https://token.actions.githubusercontent.com` and click on Get thumbprint
Input the Audience as `sts.amazonaws.com` and add Provider.
After this we can go ahead and create the role
Here is my terraform file
In my example, I am creating a IAM role with Admin Access.
condition {
test = “StringLike”
variable = “token.actions.githubusercontent.com:sub”
values = [ “repo:${var.repo_owner}/*” ]
}The above condition restricts access to repositories which are part of a particular GitHub organization or User. Not having this condition would make your role be usable by any GitHub Repository.That is definitely not desired and a major security breach.
It is possible to further restrict the role to a single repository and even to a single branch like this
condition {
test = “StringLike”
variable = “token.actions.githubusercontent.com:sub”
values = [ “repo:${var.repo_owner}/repo-name:ref:refs/heads/branch-name” ]
}But I am creating a role which can be used by all the repos of a GitHub organization or User.
The following series of commands should get your role created
terraform init
terraform plan -var='repo_owner=<your-value>' # Shows the resources
terraform apply -var='repo_owner=<your-value>'You can check in your IAM console if a role is created. The role should have a trust policy like this
Now that the role is created, it can used in the repos
Here is my workflow for deploying a lambda function using serverless framework with very standard CI/CD steps.
This workflow deploys a lambda function upon a commit to the main branch using the Serverless framework. The diagram below shows the steps involved.
The full source code of the lambda application which was deployed using my OIDC role is here.
If you find my article helpful, buy me a coffee
