Tutorial: Configure a CodeBuild-hosted GitHub Actions runner

This tutorial shows you how to configure your CodeBuild projects to run GitHub Actions jobs. For more information about using GitHub Actions with CodeBuild see Tutorial: Configure a CodeBuild-hosted GitHub Actions runner.

To complete this tutorial, you must first:

Step 1: Create a CodeBuild project with a webhook

In this step, you will create a CodeBuild project with a webhook and review it in the GitHub console. You can also choose GitHub Enterprise as your source provider. To learn more about creating a webhook within GitHub Enterprise, see GitHub manual webhooks.

Step 2: Update your GitHub Actions workflow YAML

In this step, you will update your GitHub Actions workflow YAML file in GitHub to configure your build environment and use GitHub Actions self-hosted runners in CodeBuild. For more information, see Using labels with self-hosted runners and Label overrides supported with the CodeBuild-hosted GitHub Actions runner.

Update your GitHub Actions workflow YAML

Navigate to GitHub and update the runs-on setting in your GitHub Actions workflow YAML to configure your build environment. To do so, you can do one of the following:

Run buildspec commands the INSTALL, PRE_BUILD, and POST_BUILD phases

By default, CodeBuild ignores any buildspec commands when running a self-hosted GitHub Actions build. To run buildspec commands during the build, buildspec-override:true can be added as a suffix to the label:

runs-on:
  - codebuild-<project-name>-${{ github.run_id }}-${{ github.run_attempt }}
  - buildspec-override:true

By using this command, CodeBuild will create a folder called actions-runner in the container's primary source folder. When the GitHub Actions runner starts during the BUILD phase, the runner will run in the actions-runner directory.

There are several limitations when using a buildspec override in a self-hosted GitHub Actions build:

Step 3: Review your results

Whenever a GitHub Actions workflow run occurs, CodeBuild would receive the workflow job events through the webhook. For each job in the workflow, CodeBuild starts a build to run an ephemeral GitHub Actions runner. The runner is responsible for executing a single workflow job. Once the job is completed, the runner and the associated build process will be immediately terminated.

To view your workflow job logs, navigate to your repository in GitHub, choose Actions, choose your desired workflow, and then choose the specific Job that you'd like to review the logs for.

You can review the requested labels in the log while the job is waiting to be picked up by a self-hosted runner in CodeBuild.

Once the job is completed, you will be able to view the log of the job.

Filter GitHub Actions webhook events (AWS CloudFormation)

The following YAML-formatted portion of an AWS CloudFormation template creates a filter group that triggers a build when it evaluates to true. The following filter group specifies a GitHub Actions workflow job request with a workflow name matching the regular expression \[CI-CodeBuild\].

CodeBuildProject:
  Type: AWS::CodeBuild::Project
  Properties:
    Name: MyProject
    ServiceRole: service-role
    Artifacts:
      Type: NO_ARTIFACTS
    Environment:
      Type: LINUX_CONTAINER
      ComputeType: BUILD_GENERAL1_SMALL
      Image: aws/codebuild/standard:5.0
    Source:
      Type: GITHUB
      Location: CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION
    Triggers:
      Webhook: true
      ScopeConfiguration:
        Name: organization-name
      FilterGroups:
        - - Type: EVENT
            Pattern: WORKFLOW_JOB_QUEUED
          - Type: WORKFLOW_NAME
            Pattern: \[CI-CodeBuild\]

Filter GitHub Actions webhook events (AWS CDK)

The following AWS CDK template creates a filter group that triggers a build when it evaluates to true. The following filter group specifies a GitHub Actions workflow job request.

import { aws_codebuild as codebuild } from 'aws-cdk-lib';
import {EventAction, FilterGroup} from "aws-cdk-lib/aws-codebuild";

const source = codebuild.Source.gitHub({
      owner: 'owner',
      repo: 'repo',
      webhook: true,
      webhookFilters: [FilterGroup.inEventOf(EventAction.WORKFLOW_JOB_QUEUED)],
    })

Filter GitHub Actions webhook events (Terraform)

The following Terraform template creates a filter group that triggers a build when it evaluates to true. The following filter group specifies a GitHub Actions workflow job request.

resource "aws_codebuild_webhook" "example" {
  project_name = aws_codebuild_project.example.name
  build_type   = "BUILD"
  filter_group {
    filter {
      type    = "EVENT"
      pattern = "WORKFLOW_JOB_QUEUED"
    }
  }
}