logo
Menu

GitHub Self-Hosted Runners on AWS CodeBuild

The AWS CodeBuild integration for GitHub Actions enables you to use the power of CodeBuild for your CI/CD workflows.

Published Apr 22, 2024
Last Modified Apr 30, 2024
I've written before about establishing Self-Hosted Runners within GitHub.com on AWS 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
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

Setup

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.
1
2
3
4
5
6
7
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
steps:
- 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!
1
2
3
4
5
6
7
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}-arm-3.0-small
steps:
- 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

Summary

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!
Cheers
 

Comments