How to configure AWS Credentials for GitHub Actions (the recommended way)

June 2, 2022

GitHub Actions

GitHub Actions are amazing, it's a continuous integration and continuous delivery (CI/CD) platform that allows you to automate all your software workflows. You can trigger different actions on events like push, pull-request, issue creation, or a new release, etc.

You can use pre-built actions that will allow you to automate different aspects of your pipeline without writing a single line of code.

How to configure AWS Credentials for GitHub Actions

Once of these Actions is aws-actions/configure-aws-credentials@v1 which allows you to configure AWS credential and region environment variables for use in other GitHub Actions.

Configure OpenID Connect (Cloudformation)

OpenID Connect (OIDC) is an open authentication protocol that profiles and extends OAuth 2.0 to add an identity layer. OIDC allows clients to confirm an end user’s identity using authentication by an authorization server. Implementing OIDC on top of OAuth 2.0 creates a single framework that promises to secure APIs, mobile native applications and browser applications in a single, cohesive architecture.

We are going to use CloudFormation to create the OIDC provider to allow our GitHub pipeline to assume the role we need to deploy.

Parameters:
  GitHubOrg:
    Type: String
  RepositoryName:
    Type: String
  OIDCProviderArn:
    Description: Arn for the GitHub OIDC Provider.
    Default: ""
    Type: String

Conditions:
  CreateOIDCProvider: !Equals 
    - !Ref OIDCProviderArn
    - ""

Resources:
  Role:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Statement:
          - Effect: Allow
            Action: sts:AssumeRoleWithWebIdentity
            Principal:
              Federated: !If 
                - CreateOIDCProvider
                - !Ref GitHubOidc
                - !Ref OIDCProviderArn
            Condition:
              StringLike:
                token.actions.GitHubusercontent.com:sub: !Sub repo:${GitHubOrg}/${RepositoryName}:*

  GitHubOidc:
    Type: AWS::IAM::OIDCProvider
    Condition: CreateOIDCProvider
    Properties:
      Url: https://token.actions.githubusercontent.com
      ClientIdList: 
        - sts.amazonaws.com
      ThumbprintList:
        - 6938fd4d98bab03faadb97b34396831e3780aea1

Outputs:
  Role:
    Value: !GetAtt Role.Arn

Resources created in AWS:

Fill the details for your repo: Cloudformation Input

Once you ran it you can see the role created: Cloudformation Events

If the role needs access to another repository you can update the trust relationships: Role created by Cloudformation

For instance, adding the permissions to my-other-repo, we could update the trusted entities like this:

{
    "Version": "2008-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::686669636615:oidc-provider/token.actions.GitHubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringLike": {
                    "token.actions.githubusercontent.com:sub": "repo:gonzalonaveira/naveira.dev:*"
                }
            }
        },
        {
            "Effect": "Allow",
            "Principal": {
              "Federated": "arn:aws:iam::686669636615:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
              "StringLike": {
                "token.actions.githubusercontent.com:sub": "repo:gonzalonaveira/my-other-repo:*"
              }
            }
        }
    ]
}

GitHub Workflow

You can use this Workflow as a starting point for your action. You are going to need to add more permissions to the role if you want to push an image to ECR or upload content to a S3 bucket, but that is out of the scope of this post.


name: Build and deploy

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read

    timeout-minutes: 10
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          role-to-assume: arn:aws:iam::686669636615:role/GitHubActionsOIDC-Role-11RT0ETOVXDC1
          aws-region: us-east-1

Conclusion:

We just configured our GitHub Action to use a role, which will allow us to deploy our code more often and faster.
Using a role we are secure that the credentials will not be exposed, and we can limit the access of this role.
Our team have the ability of deploying code autonomously without the need of having access to different environments.

Blog.