Deploying to AWS from GitHub Actions

A really common approach I’ve seen when people are deploying to AWS from GitHub Actions is to have an IAM user with the right permissions, and storing the the access key pair AWS_ACCESS_KEY and AWS_ACCESS_SECRET as environment variables. There are a few things I don’t personally love about doing it that way.

1. You need to set those things in your repo secrets, and then you need to re-expose them as env variables in your job setup.
2. Those keys live pretty much "forever", and it becomes your responsibility to ensure they are rotated to keep them secure. When you rotate, you need to update the key pairs everywhere you’ve used them. To me, that’s just too much work.
3. There's no way of knowing what might be using the keys

I’m a big believer in putting in a little bit more work up front to make it easier for me down the line. It’s like when I’m doing some renovation project or building some furniture; «measure four times, cut once».

Luckily there’s another way we can expose a key pair with the correct permissions! We can set up a trusted relationship between GitHub’s OIDC (OpenID Connect) and AWS, allowing GitHub to request access to AWS resources by assuming an IAM role through AWS's Security Token Service (STS).

What that means is that you can do a request new, short-lived tokens for every single deploy. No more storing secrets that need to be rotated in order to keep things secure. By using the OIDC approach, the trust relationship between GitHub and AWS is explicity defined and we can scope permissions on our IAM role for deployments, further limiting the damage that can be done to your AWS accounts if keys leak.

The setup

In order to set yourself up for this type of workflow, there’s a couple of things you need to do:

1. Create a federated identity provider in AWS to allow Github to connect
2. Create an IAM role with the correct permissions to assume when authenticating (Admin is easy but dangerous)
3. Do a deploy in order for your stack to generate the resources needed (You'll need some of the outputs later)
4. Create a workflow that uses the aws-actions/configure-aws-credentials@v4 package and is configured for which role you need
5. Deploy at will from Github when your branches update 👍

Create an Identity Provider

First off, you'll need to create an OpenID Connect Identity provider in IAM. You can either do this by going to the console, typing in a provider URL and specifying an audience, or you can do it from CloudFormation by creating a new `AWS::IAM::OIDCProvider` resource with the same parameters. We're talking about deploying Architect apps here, so I made a quick plugin to create the provider.

const plugin = {
  deploy: {
    async start({ cloudformation, stage }) {
      if (stage !== 'production') return;

      const Type = 'AWS::IAM::OIDCProvider';

      const resourceName = 'GitHubOIDCProvider';

      cloudformation.Resources = cloudformation.Resources || {};

      cloudformation.Resources[resourceName] = {
        Type,
        Properties: {
          Url: 'https://token.actions.githubusercontent.com',
          ClientIdList: ['sts.amazonaws.com'],
          ThumbprintList: ['6938fd4d98bab03faadb97b34396831e3780aea1'],
          Tags: [
            { Key: 'Name', Value: resourceName },
            { Key: 'OIDCProvider', Value: 'GitHub' },
            { Key: 'Purpose', Value: resourceName },
          ],
        },
      };

      cloudformation.Outputs = cloudformation.Outputs || {};

      cloudformation.Outputs[`${resourceName}Arn`] = {
        Description: 'ARN of the GitHub Actions OIDC Provider',
        Value: {
          'Fn::GetAtt': [resourceName, 'Arn'],
        },
      };

      return cloudformation;
    },
  },
};

export default plugin;

The plugin is fairly simple; We create a new resource with a `Type` of AWS::IAM::OIDCProvider, and call it GitHubOIDCProvider. We tell it to use https://token.actions.githubusercontent.com as the URL to authenticate to. We also add sts.amazonaws.com to the ClientIdList — which is just another word for aud in the JWT claim. The thumbprint is GitHub's default thumbprint, and is used to verify the identity of the endpoints.

Create an IAM Role

Next up we need to create an IAM role. This is the role that will be assumed when authenticating from GitHub, so it needs to have the correct set of permissions in order to do a successful deployment. Finding those permissions is tricky, so I'm just following Architect's guide for credentials to figure them out. At the time of writing, they state AdministratorAccess as the level. That is a really loose policy to apply, but given that I don't know what your app might need, and what CloudFormation might require to deploy its stack, I think it's fine.

Again, I made a plugin, but this one's a bit more involved, and requires adding some config to the .arc manifest alongside its import.

const plugin = {
  deploy: {
    async start({ cloudformation, stage, arc, inventory }) {
      if (stage !== 'production') return;

      const config = Object.fromEntries(arc['github']);

      const Type = 'AWS::IAM::Role';
      const resourceName = 'GitHubActionDeployRole';

      cloudformation.Resources = cloudformation.Resources || {};

      cloudformation.Resources[resourceName] = {
        Type,
        Properties: {
          Description:
            'Role used by GitHub Actions OIDC with Administrator Access',
          AssumeRolePolicyDocument: {
            Version: '2012-10-17',
            Statement: [
              {
                Effect: 'Allow',
                Principal: {
                  Federated: {
                    'Fn::GetAtt': ['GitHubOIDCProvider', 'Arn'],
                  },
                },
                Action: 'sts:AssumeRoleWithWebIdentity',
                Condition: {
                  StringLike: {
                    'token.actions.githubusercontent.com:sub': `repo:${config.org}/${config.repo}:*`,
                  },
                  StringEquals: {
                    'token.actions.githubusercontent.com:aud':
                      'sts.amazonaws.com',
                  },
                },
              },
            ],
          },
          ManagedPolicyArns: ['arn:aws:iam::aws:policy/AdministratorAccess'],
          Tags: [
            {
              Key: 'Name',
              Value: 'GitHubActions-Role',
            },
          ],
        },
      };

      cloudformation.Outputs = cloudformation.Outputs || {};

      cloudformation.Outputs[`${resourceName}Arn`] = {
        Description: 'ARN of the GitHub Actions Role',
        Value: {
          'Fn::GetAtt': [resourceName, 'Arn'],
        },
      };

      return cloudformation;
    },
  },
};

export default plugin;

It expects the following in .arc:

@github
org <orgname|username>
repo <repository>

Once that’s configured, you’re all set! These things could probably also be set through some environment variables, but aren’t likely to change in this context.

There’s one caveat of this approach, and that is that you need to deploy twice - once to set up the resources in AWS, and then the deployment after will use your keys instead. An idea here is to deploy once with your old action setup using access key pairs, and then you roll out your shiny new deploy action after that. That’s what I did at least :)