Let's Try - CodeBuild Managed GitHub Action Runners

Introduction

Today is a good day! AWS has announced a new feature that allows you to run GitHub action workflows on GitHub self-hosted runners managed by CodeBuild (that is a tongue twister). This feature matters because it allows you to run GitHub Actions inside AWS accounts and use the same familiar GitHub Actions workflows.

Before this feature, you would have had to self-host the runners on AWS EC2 or begrudgingly write your CI workflows in CodeBuild buildspec.yml files.

In this post, I will show you how to set up a CodeBuild project that will run GitHub Actions workflows.

Create CodeBuild Project

Navigate to the CodeBuild console and click Create build project. I am going to call the project the same name as the repository: aws-codebuild-github-action-runner.

Select the source provider as GitHub and Connect using OAuth, then click Continue to GitHub.

You will be prompted to Authorize aws-codesuite. Once you have authorized, you can select the repository and branch you want to build.

Under Primary source webhook events:

• Tick: "Rebuild every time a code change is pushed to this repository"
• Build type: "Single build"
• Webhook event filter groups: WORKFLOW_JOB_QUEUED

Note: CodeBuild will only process GitHub Actions workflow jobs events if a webhook has filter groups containing the WORKFLOW_JOB_QUEUED event filter.

For Environment select the options that best match your GitHub Actions workflow. Note that these options can be overridden by setting the run-on label later on, so for now just select the defaults.

Under "Buildspec" select "Use a buildspec file" but note that whatever you set here will be ignored, given we are using GitHub actions workflows.

Click "Create build project" to finish up the configuration.

You can confirm that the webhook has been created by navigating to the GitHub repository settings and selecting "Webhooks". In my case, this URL is: https://github.com/t04glovern/aws-codebuild-github-action-runner/settings/hooks

Create GitHub Actions Workflow

Create a new file in your repository under .github/workflows called codebuild.yml. This file will contain the GitHub Actions workflow that will trigger the CodeBuild project.

It is important to note that the runs-on label project-name must match the CodeBuild project name. In my case, the CodeBuild project name is aws-codebuild-github-action-runner so the runs-on label will be codebuild-aws-codebuild-github-action-runner-${{ github.run_id }}-${{ github.run_attempt }}.

name: Hello World

on: [push]

jobs:
  codebuild-job:
    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
    steps:
      - run: echo "Hello World!"

As I mentioned earlier, the runs-on label can also be used to override the environment settings in the CodeBuild project. For example, if you wanted to run the workflow on ARM64 you could set the runs-on label to codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-small.

A full list of the available environments can be found in the CodeBuild GitHub Action Runner documentation.

name: Hello World

on: [push]

jobs:
  codebuild-job:
    runs-on: codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-small
    steps:
      - run: echo "Hello World!"

When you push this file to your repository, the GitHub Actions workflow will trigger the CodeBuild project.

Heading over to CodeBuild you can see the build has been triggered.

From the perspective of the user, they interact with GitHub Actions as they normally would. The only difference is that the runners are managed by CodeBuild.

Conclusion

This is such a great feature and I am excited to see how it evolves. I'm a big fan of being able to customize the environment using the runs-on label as well, as it allows the repository owner to have more control over the build environment without having to modify the CodeBuild project.

What do you think of this feature? Please feel free to reach out to me on Twitter @nathangloverAUS or leave a comment below!