GitHub Self-Hosted Runners on AWS CodeBuild

GitHub Self-Hosted Runners on AWS CodeBuild


3 min read

๐Ÿ‘‹ Hey there!

I've written before about establishing Self-Hosted Runners within here. However, this involves deploying API endpoints and integrating with GitHub via a WebHook. It's not hard to establish, but it's extra work to look after, update, and manage.

That has been made much easier with the following feature I stumbled across by chance in the AWS Console.

AWS CodeBuild Related integrations

Official Documentation:- Set up self-hosted GitHub Actions runners in AWS CodeBuild

This makes things simple to set up but also gives flexibility to the GitHub Actions workflow author with some of the following benefits:-

  • Ephemeral runners, you don't need to patch!
  • Ephemeral runners that can spin up within your VPC, in your network!
  • Set the compute architecture type directly within the workflow definition
  • Access to native AWS services right from within GitHub Actions
  • There are no secrets to manage if configured via OAuth


Connect with an OAuth app

Establish an OAuth AWS CodeBuild connection to your GitHub Account. You can do this via a Personal Access Token (PAT); however, I'd recommend you don't! Using OAuth and a GitHub App is a much better way, providing fine-grained access to only what's required in GitHub.

To set this up head over to CodeBuild, Build projects, Create build project

AWS CodeBuild Create Build Project

Select GitHub as the Source.

GitHub CodeBuild Source

Click on Connect using OAuth. This will open the following window which will request access to your GitHub Account. From here you can approve access to just your account or to any GitHub Organisations you have.

GitHub Authorisation Window.

Finally, CodeBuid will ask for confirmation to establish the connection.

CodeBuild GitHub OAuth Confirmation

Once the connection is successfully established, you will be able to list the repositories within your GitHub Account or Organisations.

CodeBuid Listing GitHub Repositories

NOTE:- If you are using different credentials for your AWS & GitHub Accounts, then you may need to mess about logging in with your GitHub credentials in your browser prior to hitting the Connect to GitHub button.

Create a CodeBuild Project

With the connection established, we now create our CodeBuild Project following the steps from the AWS documentation here

The key thing that enables our integration is the WORKFLOW_JOB_QUEUED event trigger. This will trigger the codebuild project from these events within your GitHub repo.

Workflow Event Filter CodeBuild Project

Reference your CodeBuild Project in GitHub Actions

Now, back over in GitHub, we just need to update our runs-on value to trigger our CodeBuild Project.

name: Hello World
on: [push]
    runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
      - run: echo "Hello World!"

What's more is, if you want to use a different architecture, you can just override it right from within your workflow! Very powerful!

name: Hello World
on: [push]
    runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-small
      - run: echo "Hello World!"

Here is an example of the standard output from GitHub Actions running the Super-Linter on CodeBuild

GitHub Actions Job Output Here is the CloudWatch output log from the CodeBuild Project

CodeBuild Project GitHub Actions Output


This integration from AWS gives users a simple and flexible way to establish ephemeral Self-Hosted runners in AWS for GitHub Actions without the headaches of previous solutions.

It opens up so many possibilities to further integrate GitHub Actions Workflows with AWS native services. I can't wait to play with it more!

Hope someone finds this helpful!


Did you find this article valuable?

Support Stephen Jones by becoming a sponsor. Any amount is appreciated!