# Use runners with AWS CodeBuild
AWS CodeBuild supports integration with GitHub Actions runners, self-managed GitLab runners, and the Buildkite runner.
**Topics**
+ [Self-hosted GitHub Actions runners in AWS CodeBuild](action-runner-overview.md)
+ [Self-managed GitLab runners in AWS CodeBuild](gitlab-runner.md)
+ [Self-managed Buildkite runner in AWS CodeBuild](buildkite-runner.md)
# Self-hosted GitHub Actions runners in AWS CodeBuild
You can configure your project to set up self-hosted GitHub Actions runners in CodeBuild containers to process your GitHub Actions workflow jobs. This can be done by setting up a webhook using your CodeBuild project, and updating your GitHub Actions workflow YAML to use self-hosted runners hosted on CodeBuild machines.
The high-level steps to configure a CodeBuild project to run GitHub Actions jobs are as follows:
1. If you haven't done so already, create a personal access token or connect with an OAuth app to connect your project to GitHub.
1. Navigate to the CodeBuild console and create a CodeBuild project with a webhook and set up your webhook filters.
1. Update your GitHub Actions workflow YAML in GitHub to configure your build environment.
For a more detailed procedure, see [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md).
This feature allows your GitHub Actions workflow jobs to get native integration with AWS, which provides security and convenience through features like IAM, AWS Secrets Manager integration, AWS CloudTrail, and Amazon VPC. You can access latest instance types, including ARM-based instances.
**Topics**
+ [About the CodeBuild-hosted GitHub Actions runner](action-runner-questions.md)
+ [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md)
+ [Troubleshoot the webhook](action-runner-troubleshoot-webhook.md)
+ [Label overrides supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-labels.md)
+ [Compute images supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-yaml.images.md)
# About the CodeBuild-hosted GitHub Actions runner
The following are some common questions about the CodeBuild-hosted GitHub Actions runner.
## When should I include the image and instance overrides in the label?
You can include the image and instance overrides in the label in order to specify different build environment for each of your GitHub Actions workflow jobs. This can be done without the need to create multiple CodeBuild projects or webhooks. For example, this is useful when you need to use a [matrix for your workflow jobs](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs).
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
image:${{ matrix.os }}
instance-size:${{ matrix.size }}
strategy:
matrix:
include:
- os: arm-3.0
size: small
- os: linux-5.0
size: large
steps:
- run: echo "Hello World!"
```
**Note**
Quotation marks might be required if `runs-on` has multiple labels containing GitHub Actions context.
## Can I use CloudFormation for this feature?
Yes, you can include a filter group in your CloudFormation template that specifies a GitHub Actions workflow job event filter in your project webhook.
```
Triggers:
Webhook: true
FilterGroups:
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
```
For more information, see [Filter GitHub webhook events (CloudFormation)](github-webhook-events-cfn.md).
If you need help setting up project credentials in your CloudFormation template, see [AWS::CodeBuild::SourceCredential](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-sourcecredential.html) in the *AWS CloudFormation User Guide* for more information.
## How can I mask secrets when using this feature?
By default, secrets that are printed in the log is not masked. If you would like to mask your secrets, you can use the following syntax: `::add-mask::value`. The following is an example of how you can use this syntax in your YAML:
```
name: Secret Job
on: [push]
jobs:
Secret-Job:
runs-on: codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
env:
SECRET_NAME: "secret-name"
steps:
- run: echo "::add-mask::$SECRET_NAME"
```
For more information, see [Masking a value in a log](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#masking-a-value-in-a-log) on GitHub.
## Can I receive GitHub Actions webhook events from multiple repositories within a single project?
CodeBuild supports organization and global level webhooks, which receive events from a specified organization or enterprise. For more information, see [GitHub global and organization webhooks](github-global-organization-webhook.md).
## Which regions support using a CodeBuild-hosted GitHub Actions runner?
CodeBuild-hosted GitHub Actions runners are supported in all CodeBuild regions. For more information about AWS Regions where CodeBuild is available, see [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
## Which platforms support using a CodeBuild-hosted GitHub Actions runner?
CodeBuild-hosted GitHub Actions runners are supported on both Amazon EC2 and [AWS Lambda](lambda.md) compute. You can use the following platforms: Amazon Linux 2, Amazon Linux 2023, Ubuntu, and Windows Server Core 2019. For more information, see [EC2 compute images](ec2-compute-images.md) and [Lambda compute images](lambda-compute-images.md).
# 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](#action-runner).
To complete this tutorial, you must first:
+ Connect with a personal access token, a Secrets Manager secret, OAuth app, or GitHub App. If you'd like to connect with an OAuth app, you must use the CodeBuild console to do so. If you'd like to create a personal access token, you can either use the CodeBuild console or use the [ImportSourceCredentials API](https://docs.aws.amazon.com/codebuild/latest/APIReference/API_ImportSourceCredentials.html). For more instructions, see [GitHub and GitHub Enterprise Server access in CodeBuild](access-tokens-github-overview.md).
+ Connect CodeBuild to your GitHub account. To do so, you can do one of the following:
+ You can add GitHub as a source provider in the console. You can connect with either a personal access token, a Secrets Manager secret, OAuth app, or GitHub App. For instructions, see [GitHub and GitHub Enterprise Server access in CodeBuild](access-tokens-github-overview.md).
+ You can import your GitHub credentials via the [ImportSourceCredentials API](https://docs.aws.amazon.com/cli/latest/reference/codebuild/import-source-credentials.html). This can only be done with a personal access token. If you connect using an OAuth app, you must connect using the console instead. For instructions, see [Connect GitHub with an access token (CLI)](access-tokens-github.md#access-tokens-github-cli).
**Note**
This only needs to be done if you haven't connected to GitHub for your account.
## 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](github-manual-webhook.md).
**To create a CodeBuild project with a webhook**
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
1. In **Project type**, choose **Runner project**.
In **Runner**:
1. For **Runner provider**, choose **GitHub**.
1. For **Runner location**, choose **Repository**.
1. For Repository URL under **Repository**, choose **https://github.com/user-name/repository-name**.
**Note**
By default, your project will only receive `WORKFLOW_JOB_QUEUED` events for a single repository. If you would like to receive events for all repositories within an organization or enterprise, see [GitHub global and organization webhooks](github-global-organization-webhook.md).
1.
+ In **Environment**:
+ Choose a supported **Environment image** and **Compute**. Note that you have the option to override the image and instance settings by using a label in your GitHub Actions workflow YAML. For more information, see [Step 2: Update your GitHub Actions workflow YAML](#sample-github-action-runners-update-yaml)
+ In **Buildspec**:
+ Note that your buildspec will be ignored unless `buildspec-override:true` is added as a label. Instead, CodeBuild will override it to use commands that will setup the self-hosted runner.
1. Continue with the default values and then choose **Create build project**.
1. Open the GitHub console at `https://github.com/user-name/repository-name/settings/hooks` to verify that a webhook has been created and is enabled to deliver **Workflow jobs** events.
## Step 2: Update your GitHub Actions workflow YAML
In this step, you will update your GitHub Actions workflow YAML file in [https://github.com/](https://github.com/) to configure your build environment and use GitHub Actions self-hosted runners in CodeBuild. For more information, see [Using labels with self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners) and [Label overrides supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-labels.md).
### Update your GitHub Actions workflow YAML
Navigate to [https://github.com/](https://github.com/) and update the [https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners) setting in your GitHub Actions workflow YAML to configure your build environment. To do so, you can do one of the following:
+ You can specify the project name and run ID, in which case the build will use your existing project configuration for the compute, image, image version, and instance size. The project name is needed to link the AWS-related settings of your GitHub Actions job to a specific CodeBuild project. By including the project name in the YAML, CodeBuild is allowed to invoke jobs with the correct project settings. By providing the run ID, CodeBuild will map your build to specific workflow runs and stop the build when the workflow run is cancelled. For more information, see [`github` context](https://docs.github.com/en/actions/learn-github-actions/contexts#github-context).
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}
```
**Note**
Make sure that your ** matches the name of the project that you created in the previous step. If it doesn't match, CodeBuild will not process the webhook and the GitHub Actions workflow might hang.
The following is an example of a GitHub Actions workflow YAML:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
steps:
- run: echo "Hello World!"
```
+ You can also override your image and compute type in the label. See [Compute images supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-yaml.images.md) for a list of curated images. For using custom images, see [Label overrides supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-labels.md). The compute type and image in the label will override the environment settings on your project. To override your environment settings for an CodeBuild EC2 or Lambda compute build, use the following syntax:
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
image:-
instance-size:
```
The following is an example of a GitHub Actions workflow YAML:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
image:arm-3.0
instance-size:small
steps:
- run: echo "Hello World!"
```
+ You can override the fleet used for your build in the label. This will override the fleet settings configured on your project to use the specified fleet. For more information, see [Run builds on reserved capacity fleets](fleets.md). To override your fleet settings for an Amazon EC2 compute build, use the following syntax:
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
fleet:
```
To override both the fleet and the image used for the build, use the following syntax:
```
runs-on:
- codebuild--${{ github.run_id }}-${{ github.run_attempt }}
fleet:
image:-
```
The following is an example of a GitHub Actions workflow YAML:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
fleet:myFleet
image:arm-3.0
steps:
- run: echo "Hello World!"
```
+ In order to run your GitHub Actions jobs on a custom image, you can configure a custom image in your CodeBuild project and avoid providing an image override label. CodeBuild will use the image configured in the project if no image override label is provided.
+ Optionally, you can provide labels outside of those that CodeBuild supports. These labels will be ignored for the purpose of overriding attributes of the build, but will not fail the webhook request. For example, adding `testLabel` as a label will not prevent the build from running.
**Note**
If a dependency provided by GitHub-hosted runners is unavailable in the CodeBuild environment, you can install the dependency using GitHub Actions in your workflow run. For example, you can use the [https://github.com/actions/setup-python](https://github.com/actions/setup-python) action to install Python for your build environment.
### Run buildspec commands the INSTALL, PRE\$1BUILD, and POST\$1BUILD 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--${{ 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:
+ CodeBuild will not run buildspec commands during the `BUILD` phase, as the self-hosted runner runs in the `BUILD` phase.
+ CodeBuild will not download any primary or secondary sources during the `DOWNLOAD_SOURCE` phase. If you have a buildspec file configured, only that file will be downloaded from the project's primary source.
+ If a build command fails in the `PRE_BUILD` or `INSTALL` phase, CodeBuild will not start the self-hosted runner and the GitHub Actions workflow job will need to be cancelled manually.
+ CodeBuild fetches the runner token during the `DOWNLOAD_SOURCE` phase, which has an expiration time of one hour. If your `PRE_BUILD` or `INSTALL` phases exceed an hour, the runner token may expire before the GitHub self-hosted runner starts.
## 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.
![\[Loading the log of the job.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/hello-world-loading.png)
Once the job is completed, you will be able to view the log of the job.
![\[The log of the job.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/hello-world-log.png)
## GitHub Actions runner configuration options
You can specify the following environment variables in your project configuration to modify the setup configuration of your self-hosted runners.
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME`
CodeBuild will register self-hosted runners to the organization name specified as the value of this environment variable. For more information about registering runners at the organization level and the necessary permissions, see [ Create configuration for a just-in-time runner for an organization](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-organization).
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ENTERPRISE_REGISTRATION_NAME`
CodeBuild will register self-hosted runners to the enterprise name specified as the value of this environment variable. For more information about registering runners at the enterprise level and the necessary permissions, see [ Create configuration for a just-in-time runner for an Enterprise](https://docs.github.com/en/enterprise-server/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-enterprise).
Enterprise runners are not available to organization repositories by default. For self-hosted runners to pick up workflow jobs, you might need to configure your runner group access settings. For more information, see [ Making enterprise runners available to repositories](https://docs.github.com/en/enterprise-server/actions/hosting-your-own-runners/managing-self-hosted-runners/adding-self-hosted-runners#making-enterprise-runners-available-to-repositories).
`CODEBUILD_CONFIG_GITHUB_ACTIONS_RUNNER_GROUP_ID`
CodeBuild will register self-hosted runners to the integer runner group ID stored as the value of this environment variable. By default, this value is 1. For more information about self-hosted runner groups, see [ Managing access to self-hosted runners using groups](https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28#create-configuration-for-a-just-in-time-runner-for-an-organization).
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ORG_REGISTRATION_NAME`
To configure organization level runner registration using your GitHub Actions workflow YAML file, you can use the following syntax:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
organization-registration-name:myOrganization
steps:
- run: echo "Hello World!"
```
`CODEBUILD_CONFIG_GITHUB_ACTIONS_ENTERPRISE_REGISTRATION_NAME`
To configure enterprise level runner registration using your GitHub Actions workflow YAML file, you can use the following syntax:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
enterprise-registration-name:myEnterprise
steps:
- run: echo "Hello World!"
```
`CODEBUILD_CONFIG_GITHUB_ACTIONS_RUNNER_GROUP_ID`
To configure registering runners to a specific runner group ID using your GitHub Actions workflow YAML file, you can use the following syntax:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
registration-group-id:3
steps:
- run: echo "Hello World!"
```
## Filter GitHub Actions webhook events (CloudFormation)
The following YAML-formatted portion of an 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
Scope: GITHUB_ORGANIZATION
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"
}
}
}
```
## Filter GitHub Actions webhook events (AWS CLI)
The following AWS CLI commands create a self-hosted GitHub Actions runner project with a GitHub Actions workflow job request filter group that triggers a build when it evaluates to true.
```
aws codebuild create-project \
--name \
--source "{\"type\":\"GITHUB\",\"location\":\"\",\"buildspec\":\"\"}" \
--artifacts {"\"type\":\"NO_ARTIFACTS\""} \
--environment "{\"type\": \"LINUX_CONTAINER\",\"image\": \"aws/codebuild/amazonlinux-x86_64-standard:5.0\",\"computeType\": \"BUILD_GENERAL1_MEDIUM\"}" \
--service-role ""
```
```
aws codebuild create-webhook \
--project-name \
--filter-groups "[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"}]]"
```
# Troubleshoot the webhook
**Issue: **The webhook you set up in [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md) isn't working or your workflow job is hanging on GitHub.
**Possible causes: **
+ Your webhook **Workflow jobs** event might be failing to trigger a build. Review the **Response** logs to view the response or error message.
+ Your jobs are being assigned to the incorrect runner agent due to their label configuration. This issue can occur when one of your jobs within a single workflow run has fewer labels than another job. For example, if you have two jobs with the following labels in the same workflow run:
+ **Job 1**: `codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}`
+ **Job 2**: `codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}`, `instance-size:medium`
When routing a self-hosted GitHub Actions job, GitHub will route the job to any runner with all the job's specified labels. This behavior means that **Job 1** can be picked up by either the runner created for **Job 1** or **Job 2**, but **Job 2** can only be picked up by the runner created for **Job 2** since it has an additional label. If **Job 1** is picked up by the runner created for **Job 2**, then **Job 2** will become stuck since the **Job 1** runner doesn't have the `instance-size:medium` label.
**Recommended solutions: **
When creating multiple jobs within the same workflow run, use the same number of label overrides for each job or assign each job a custom label, such as `job1` or `job2`.
If the error persists, use the following instructions to debug the issue.
1. Open the GitHub console at `https://github.com/user-name/repository-name/settings/hooks` to view your repository's webhook settings. On this page, you'll see a webhook that was created for your repository.
1. Choose **Edit** and confirm that the webhook is enabled to deliver **Workflow jobs** events.
![\[Workflow job events are enabled in your webhook.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-actions-workflow-jobs.png)
1. Navigate to the **Recent Deliveries** tab, find the corresponding `workflow_job.queued` event, and expand the event.
1. Review the **labels** field in the **Payload** and make sure it’s as expected.
1. Finally, review the **Response** tab, as this contains the response or error message returned from CodeBuild.
![\[The response or error message returned from CodeBuild.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/github-actions-workflow-jobs-response.png)
1. Alternatively, you can debug webhook failures using GitHub's APIs. You can view recent deliveries for a webhook using the [ List deliveries for a repository webhook](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#list-deliveries-for-a-repository-webhook) API:
```
gh api \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
/repos/owner/repo/hooks/hook-id/deliveries
```
After finding the webhook delivery you're looking to debug and noting the delivery ID, you can use the [ Get a delivery for a repository webhook](https://docs.github.com/en/rest/repos/webhooks?apiVersion=2022-11-28#get-a-delivery-for-a-repository-webhook) API. CodeBuild's response to the webhook's delivery payload can be found in the `response` section:
```
gh api \
-H "Accept: application/vnd.github+json" \
-H "X-GitHub-Api-Version: 2022-11-28" \
/repos/owner/repo/hooks/hook-id/deliveries/delivery-id
```
**Issue:** Your GitHub Actions with [deployment protection](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/reviewing-deployments) rules enabled triggers builds within CodeBuild before the deployment has been approved.
**Possible causes:** CodeBuild fetches the deployment and environment associated with the GitHub Actions job if they exist to verify if the is approved. If CodeBuild fails to fetch either the deployment or environment, the CodeBuild build may be triggered prematurely.
**Recommended solutions:** Verify that the credentials associated with your CodeBuild projects have read permissions for deployments and actions within GitHub.
# Label overrides supported with the CodeBuild-hosted GitHub Actions runner
In your GitHub Actions workflow YAML, you can provide a variety of label overrides that modify your self-hosted runner build. Any builds not recognized by CodeBuild will be ignored but will not fail your webhook request. For example, the following workflow YAML includes overrides for image, instance size, fleet, and the buildspec:
```
name: Hello World
on: [push]
jobs:
Hello-World-Job:
runs-on:
- codebuild-myProject-${{ github.run_id }}-${{ github.run_attempt }}
image:${{ matrix.os }}
instance-size:${{ matrix.size }}
fleet:myFleet
buildspec-override:true
strategy:
matrix:
include:
- os: arm-3.0
size: small
- os: linux-5.0
size: large
steps:
- run: echo "Hello World!"
```
**Note**
If your workflow job is hanging on GitHub, see [Troubleshoot the webhook](action-runner-troubleshoot-webhook.md) and [ Using custom labels to route jobs](https://docs.github.com/en/enterprise-server@3.12/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow?learn=hosting_your_own_runners&learnProduct=actions#using-custom-labels-to-route-jobs).
`codebuild--${{github.run_id}}-${{github.run_attempt}}` (required)
+ Example: `codebuild-fake-project-${{ github.run_id }}-${{ github.run_attempt }}`
+ Required for all GitHub Actions workflow YAMLs. ** should be equal to the name of the project for which the self-hosted runner webhook is configured.
`image:-`
+ Example: `image:arm-3.0`
+ Overrides the image and environment type used when starting the self-hosted runner build with a curated image. To learn about supported values, see [Compute images supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-yaml.images.md).
+ To override the image and environment type used with a custom image, use `image:custom--`
+ Example: `image:custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0`
**Note**
If the custom image resides in a private registry, see [Configure a private registry credential for self-hosted runners](private-registry-sample-configure-runners.md).
`instance-size:`
+ Example: `instance-size:medium`
+ Overrides the instance type used when starting the self-hosted runner build. To learn about supported values, see [Compute images supported with the CodeBuild-hosted GitHub Actions runner](sample-github-action-runners-update-yaml.images.md).
`fleet:`
+ Example: `fleet:myFleet`
+ Overrides the fleet settings configured on your project to use the specified fleet. For more information, see [Run builds on reserved capacity fleets](fleets.md).
`buildspec-override:`
+ Example: `buildspec-override:true`
+ Allows the build to run buildspec commands in the `INSTALL`, `PRE_BUILD`, and `POST_BUILD` phases if set to `true`.
## Single label override (legacy)
CodeBuild allows you to provide multiple overrides in a single label using the following:
+ To override your environment settings for an Amazon EC2/Lambda compute build, use the following syntax:
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}---
```
+ To override your fleet settings for Amazon EC2 compute build, use the following syntax:
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}-fleet-
```
+ To override both the fleet and the image used for the build, use the following syntax:
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}-image--fleet-
```
+ To run buildspec commands during the build, `-with-buildspec` can be added as a suffix to the label:
```
runs-on: codebuild--${{ github.run_id }}-${{ github.run_attempt }}----with-buildspec
```
+ Optionally, you can provide an instance size override without overriding the image. For Amazon EC2 builds, you can exclude both environment type and image identifier. For Lambda builds, you can exclude the image identifier.
# Compute images supported with the CodeBuild-hosted GitHub Actions runner
In the label you configured in [Tutorial: Configure a CodeBuild-hosted GitHub Actions runner](action-runner.md), you can override your Amazon EC2 environment settings by using the values in the first three columns. CodeBuild provides the following Amazon EC2 compute images. For more information about
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-action-runners-update-yaml.images.html)
In addition, you can override your Lambda environment settings by using the following values. For more information about CodeBuild Lambda compute, see [Run builds on AWS Lambda compute](lambda.md). CodeBuild supports the following Lambda compute images:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-github-action-runners-update-yaml.images.html)
For more information, see [Build environment compute modes and types](build-env-ref-compute-types.md) and [Docker images provided by CodeBuild](build-env-ref-available.md).
# Self-managed GitLab runners in AWS CodeBuild
GitLab provides two execution modes to run GitLab jobs in your CI/CD pipeline. One mode is GitLab-hosted runners, which are managed by GitLab and fully integrated with GitLab. The other mode is self-managed runners, which allows you to bring your own customized environment to run jobs in the GitLab CI/CD pipeline.
The high-level steps to configure a CodeBuild project to run GitLab CI/CD pipeline jobs are as follows:
1. If you haven't done so already, connect with an OAuth app to connect your project to GitLab.
1. Navigate to the CodeBuild console and create a CodeBuild project with a webhook and set up your webhook filters.
1. Update your GitLab CI/CD pipeline YAML in GitLab to configure your build environment.
For a more detailed procedure, see [Tutorial: Configure a CodeBuild-hosted GitLab runner](sample-gitlab-runners.md).
This feature allows your GitLab CI/CD pipeline jobs to get native integration with AWS, which provides security and convenience through features like IAM, AWS CloudTrail, and Amazon VPC. You can access latest instance types, including ARM-based instances.
**Topics**
+ [About the CodeBuild-hosted GitLab runner](gitlab-runner-questions.md)
+ [Tutorial: Configure a CodeBuild-hosted GitLab runner](sample-gitlab-runners.md)
+ [Label overrides supported with the CodeBuild-hosted GitLab runner](gitlab-runners-update-labels.md)
+ [Compute images supported with the CodeBuild-hosted GitLab runner](sample-gitlab-runners-gitlab-ci.images.md)
# About the CodeBuild-hosted GitLab runner
The following are some common questions about the CodeBuild-hosted GitLab runner.
## What source types are supported for CodeBuild-hosted GitLab runners?
CodeBuild-hosted GitLab runners are supported for the `GITLAB` and `GITLAB_SELF_MANAGED` source type.
## When should I include the image and instance overrides in the label?
You can include the image and instance overrides in the label in order to specify different build environment for each of your GitLab CI/CD pipeline jobs. This can be done without the need to create multiple CodeBuild projects or webhooks.
## Can I use CloudFormation for this feature?
Yes, you can include a filter group in your CloudFormation template that specifies a GitLab workflow job event filter in your project webhook.
```
Triggers:
Webhook: true
FilterGroups:
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
```
For more information, see [Filter GitLab webhook events (CloudFormation)](gitlab-webhook-events-cfn.md).
If you need help setting up project credentials in your CloudFormation template, see [AWS::CodeBuild::SourceCredential](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-codebuild-sourcecredential.html) in the *AWS CloudFormation User Guide* for more information.
## How can I mask secrets when using this feature?
By default, secrets that are printed in the log is not masked. If you would like to mask your secrets, you can do so by updating your CI/CD environment variable settings:
**To mask secrets in GitLab**
1. In your **GitLab Settings**, choose **CI/CD**.
1. In **Variables**, choose **Edit** for the secret you'd like to mask.
1. In **Visibility**, select **Mask variable**, and then choose **Update variable** to save your changes.
## Can I receive GitLab webhook events from multiple projects within a single group?
CodeBuild supports group webhooks, which receive events from a specified GitLab group. For more information, see [GitLab group webhooks](gitlab-group-webhook.md).
## Can I execute a job in docker executor for the self-managed runner? For example, I want to run a pipeline job on a specific image to maintain the same build environment in a separate and isolated container.
You can run the GitLab self-managed runner in CodeBuild with a specific image by [creating the project with a custom image](create-project.md#environment-image.console) or [overriding the image](sample-gitlab-runners.md#sample-gitlab-runners-gitlab-ci) in your `.gitlab-ci.yml` file.
## What executor does the self-managed runner in CodeBuild run with?
The self-managed runner in CodeBuild runs with the shell executor, where the build runs locally along with the GitLab runner that is running inside the docker container.
## Can I provide buildspec commands along with the self-managed runner?
Yes, it is possible to add buildspec commands along with self-managed runner. You can provide the buildspec.yml file in your GitLab repository and use the `buildspec-override:true` tag in the **Tags** section of the job. For more information, see [Buildspec file name and storage location](build-spec-ref.md#build-spec-ref-name-storage).
## Which regions support using a CodeBuild-hosted GitLab runner?
CodeBuild-hosted GitLab runners are supported in all CodeBuild regions. For more information about AWS Regions where CodeBuild is available, see [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
## Which platforms support using a CodeBuild-hosted GitLab runner?
CodeBuild-hosted GitLab runners are supported on both Amazon EC2 and [AWS Lambda](lambda.md) compute. You can use the following platforms: Amazon Linux 2, Amazon Linux 2023, Ubuntu, and Windows Server Core 2019. For more information, see [EC2 compute images](ec2-compute-images.md) and [Lambda compute images](lambda-compute-images.md).
# Tutorial: Configure a CodeBuild-hosted GitLab runner
This tutorial shows you how to configure your CodeBuild projects to run GitLab CI/CD pipeline jobs. For more information about using GitLab or GitLab Self Managed with CodeBuild, see [Self-managed GitLab runners in AWS CodeBuild](gitlab-runner.md).
To complete this tutorial, you must first:
+ Connect with a OAuth app by using CodeConnections. Note that when connecting with an OAuth app, you must use the CodeBuild console to do so. For more instructions, see [GitLab access in CodeBuild](access-tokens-gitlab-overview.md).
+ Connect CodeBuild to your GitLab account. To do so, you can add GitLab as a source provider in the console. For instructions, see [GitLab access in CodeBuild](access-tokens-gitlab-overview.md).
**Note**
This only needs to be done if you haven't connected to GitLab for your account.
With this feature, CodeBuild needs additional permissions. such as `create_runner` and `manage_runner` from the GitLab OAuth app. If there are existing CodeConnections for a particular GitLab account, then it doesn't automatically request for permission updates. To do so, you can go to the CodeConnections console and create a dummy connection to the same GitLab account to trigger the reauthorization to get the additional prmissions. With this, all the existing connections can use the runner feature. Once complete, you can delete the dummy connection.
## 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 GitLab console.
**To create a CodeBuild project with a webhook**
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
In **Project type**, choose **Runner project**.
+ In **Runner**:
+ For **Runner provider**, choose **GitLab**.
+ For **Credential**, choose one of the following:
+ Choose ** Default source credential**. Default connection applies a default GitLab connection across all projects.
+ Choose ** Custom source credential**. Custom connection applies a custom GitLab connection that overrides your account's default settings.
**Note**
If you have not already created a connection to your provider, you'll have to create a new GitLab connection. For instructions, see [Connect CodeBuild to GitLab](access-tokens-gitlab-overview.md#connections-gitlab).
+ For **Runner location**, choose **Repository**.
+ For **Repository**, choose the name of your project in GitLab by specifying the project path with the namespace.
+ In **Environment**:
+ Choose a supported **Environment image** and **Compute**. Note that you have the option to override the image and instance settings by using a label in your GitLab CI/CD pipeline YAML. For more information, see [Step 2: Create a .gitlab-ci.yml file in your repository](#sample-gitlab-runners-gitlab-ci).
+ In **Buildspec**:
+ Note that your buildspec will be ignored unless `buildspec-override:true` is added as a label. Instead, CodeBuild will override it to use commands that will setup the self-managed runner.
1. Continue with the default values and then choose **Create build project**.
1. Open the GitLab console at `https://gitlab.com/user-name/repository-name/-/hooks` to verify that a webhook has been created and is enabled to deliver **Workflow jobs** events.
## Step 2: Create a .gitlab-ci.yml file in your repository
In this step, you will create a `.gitlab-ci.yml` file in [https://gitlab.com/](https://gitlab.com/) to configure your build environment and use GitLab self-managed runners in CodeBuild. For more information, see [Use self-managed runners](https://docs.gitlab.com/runner/#use-self-managed-runners).
### Update your GitLab CI/CD pipeline YAML
Navigate to `https://gitlab.com/user-name/project-name/-/tree/branch-name` and create a `.gitlab-ci.yml` file in your repository. You can configure your build environment by doing one of the following:
+ You can specify the CodeBuild project name, in which case the build will use your existing project configuration for the compute, image, image version, and instance size. The project name is needed to link the AWS-related settings of your GitLab job to a specific CodeBuild project. By including the project name in the YAML, CodeBuild is allowed to invoke jobs with the correct project settings.
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
```
`$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME` is required to map the build to specific pipeline job runs and stop the build when the pipeline run is cancelled.
**Note**
Make sure that your ** matches the name of the project that you created in CodeBuild. If it doesn't match, CodeBuild will not process the webhook and the GitLab CI/CD pipeline might hang.
The following is an example of a GitLab CI/CD pipeline YAML:
```
workflow:
name: HelloWorld
stages: # List of stages for jobs, and their order of execution
- build
build-job: # This job runs in the build stage, which runs first.
stage: build
script:
- echo "Hello World!"
tags:
- codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
```
+ You can also override your image and compute type in the tag. See [Compute images supported with the CodeBuild-hosted GitLab runner](sample-gitlab-runners-gitlab-ci.images.md) for a list of curated images. For using custom images, see [Label overrides supported with the CodeBuild-hosted GitLab runner](gitlab-runners-update-labels.md). The compute type and image in the tag will override the environment settings on your project. To override your environment settings for an Amazon EC2 compute build, use the following syntax:
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- image:-
- instance-size:
```
The following is an example of a GitLab CI/CD pipeline YAML:
```
stages:
- build
build-job:
stage: build
script:
- echo "Hello World!"
tags:
- codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- image:arm-3.0
- instance-size:small
```
+ You can override the fleet used for your build in the tag. This will override the fleet settings configured on your project to use the specified fleet. For more information, see [Run builds on reserved capacity fleets](fleets.md). To override your fleet settings for an Amazon EC2 compute build, use the following syntax:
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- fleet:
```
To override both the fleet and the image used for the build, use the following syntax:
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- fleet:
- image:-
```
The following is an example of a GitLab CI/CD pipeline YAML:
```
stages:
- build
build-job:
stage: build
script:
- echo "Hello World!"
tags:
- codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- fleet:myFleet
- image:arm-3.0
```
+ In order to run your GitLab CI/CD pipeline jobs on a custom image, you can configure a custom image in your CodeBuild project and avoid providing an image override label. CodeBuild will use the image configured in the project if no image override label is provided.
After you commit your changes to `.gitlab-ci.yml`, a GitLab pipeline will be triggered and the `build-job` will send a webhook notification that will start your build in CodeBuild.
### Run buildspec commands the INSTALL, PRE\$1BUILD, and POST\$1BUILD phases
By default, CodeBuild ignores any buildspec commands when running a self-managed GitLab build. To run buildspec commands during the build, `buildspec-override:true` can be added as a suffix to `tags`:
```
tags:
- codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- buildspec-override:true
```
By using this command, CodeBuild will create a folder called `gitlab-runner` in the container's primary source folder. When the GitLab runner starts during the `BUILD` phase, the runner will run in the `gitlab-runner` directory.
There are several limitations when using a buildspec override in a self-managed GitLab build:
+ CodeBuild will not run buildspec commands during the `BUILD` phase, as the self-managed runner runs in the `BUILD` phase.
+ CodeBuild will not download any primary or secondary sources during the `DOWNLOAD_SOURCE` phase. If you have a buildspec file configured, only that file will be downloaded from the project's primary source.
+ If a build command fails in the `PRE_BUILD` or `INSTALL` phase, CodeBuild will not start the self-managed runner and the GitLab CI/CD pipeline job will need to be cancelled manually.
+ CodeBuild fetches the runner token during the `DOWNLOAD_SOURCE` phase, which has an expiration time of one hour. If your `PRE_BUILD` or `INSTALL` phases exceed an hour, the runner token may expire before the GitLab self-managed runner starts.
## Step 3: Review your results
Whenever a GitLab CI/CD pipeline run occurs, CodeBuild would receive the CI/CD pipeline job events through the webhook. For each job in the CI/CD pipeline, CodeBuild starts a build to run an ephemeral GitLab runner. The runner is responsible for executing a single CI/CD pipeline job. Once the job is completed, the runner and the associated build process will be immediately terminated.
To view your CI/CD pipeline job logs, navigate to your repository in GitLab, choose **Build**, **Jobs**, 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-managed runner in CodeBuild.
## Filter GitLab webhook events (CloudFormation)
The following YAML-formatted portion of an CloudFormation template creates a filter group that triggers a build when it evaluates to true. The following filter group specifies a GitLab CI/CD pipeline job request with a CI/CD pipeline 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: GITLAB
Location: CODEBUILD_DEFAULT_WEBHOOK_SOURCE_LOCATION
Triggers:
Webhook: true
ScopeConfiguration:
Name: group-name
Scope: GITLAB_GROUP
FilterGroups:
- - Type: EVENT
Pattern: WORKFLOW_JOB_QUEUED
- Type: WORKFLOW_NAME
Pattern: \[CI-CodeBuild\]
```
# Label overrides supported with the CodeBuild-hosted GitLab runner
In your GitLab CI/CD pipeline YAML, you can provide a variety of label overrides that modify your self-managed runner build. Any builds not recognized by CodeBuild will be ignored but will not fail your webhook request. For example, the following YAML includes overrides for image, instance size, fleet, and the buildspec:
```
workflow:
name: HelloWorld
stages:
- build
build-job:
stage: build
script:
- echo "Hello World!"
tags:
- codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME
- image:arm-3.0
- instance-size:small
- fleet:myFleet
- buildspec-override:true
```
`codebuild--$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME` (required)
+ Example: `codebuild-myProject-$CI_PROJECT_ID-$CI_PIPELINE_IID-$CI_JOB_NAME`
+ Required for all GitLab CI/CD pipeline YAMLs. ** should be equal to the name of the project for which the self-managed runner webhook is configured.
`image:-`
+ Example: `image:arm-3.0`
+ Overrides the image and environment type used when starting the self-managed runner build. To learn about supported values, see [Compute images supported with the CodeBuild-hosted GitLab runner](sample-gitlab-runners-gitlab-ci.images.md).
+ To override the image and environment type used with a custom image, use `image:custom--`
+ Example: `image:custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0`
**Note**
If the custom image resides in a private registry, see [Configure a private registry credential for self-hosted runners](private-registry-sample-configure-runners.md).
`instance-size:`
+ Example: `instance-size:small`
+ Overrides the instance type used when starting the self-managed runner build. To learn about supported values, see [Compute images supported with the CodeBuild-hosted GitLab runner](sample-gitlab-runners-gitlab-ci.images.md).
`fleet:`
+ Example: `fleet:myFleet`
+ Overrides the fleet settings configured on your project to use the specified fleet. For more information, see [Run builds on reserved capacity fleets](fleets.md).
`buildspec-override:`
+ Example: `buildspec-override:true`
+ Allows the build to run buildspec commands in the `INSTALL`, `PRE_BUILD`, and `POST_BUILD` phases if set to `true`.
# Compute images supported with the CodeBuild-hosted GitLab runner
In the label you configured in [Tutorial: Configure a CodeBuild-hosted GitLab runner](sample-gitlab-runners.md), you can override your Amazon EC2 environment settings by using the values in the first three columns. CodeBuild provides the following Amazon EC2 compute images. For more information about
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-gitlab-runners-gitlab-ci.images.html)
In addition, you can override your Lambda environment settings by using the following values. For more information about CodeBuild Lambda compute, see [Run builds on AWS Lambda compute](lambda.md). CodeBuild supports the following Lambda compute images:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/sample-gitlab-runners-gitlab-ci.images.html)
For more information, see [Build environment compute modes and types](build-env-ref-compute-types.md) and [Docker images provided by CodeBuild](build-env-ref-available.md).
# Self-managed Buildkite runner in AWS CodeBuild
You can configure your project to set up self-hosted Buildkite runners in CodeBuild containers to process your Buildkite jobs. This can be done by setting up a webhook using your CodeBuild project, and updating your Buildkite pipeline YAML steps to use self-hosted runners hosted on CodeBuild machines.
The high-level steps to configure a CodeBuild project to run Buildkite jobs are as follows:
+ Navigate to the CodeBuild console and create a CodeBuild project with the Buildkite runner project runner type configuration
+ Add a `job.scheduled` webhook to your Buildkite organization.
+ Update your Buildkite pipeline YAML steps in Buildkite to configure your build environment.
For a more detailed procedure, see [Tutorial: Configure a CodeBuild-hosted Buildkite runner](sample-runner-buildkite.md). This feature allows your Buildkite jobs to get native integration with AWS, which provides security and convenience through features like IAM, AWS Secrets Manager, AWS CloudTrail, and Amazon VPC. You can access the latest instance types, including ARM-based instances.
# About the CodeBuild-hosted Buildkite runner
The following are some common questions about the CodeBuild-hosted Buildkite runner.
## When should I include the image and instance overrides in the label?
You can include the image and instance overrides in the label in order to specify different build environment for each of your Buildkite jobs. This can be done without the need to create multiple CodeBuild projects or webhooks. For example, this is useful when you need to use a [matrix for Buildkite jobs](https://buildkite.com/docs/pipelines/configure/workflows/build-matrix).
```
agents:
queue: "myQueue"
steps:
- command: "echo \"Hello World\""
agents:
project: "codebuild-myProject"
image: "{{matrix.os}}"
instance-size: "{{matrix.size}}"
matrix:
setup:
os:
- "arm-3.0"
- "al2-5.0"
size:
- "small"
- "large"
```
## Can CodeBuild create webhooks within Buildkite automatically?
Currently, Buildkite requires that all webhooks are created manually using their console. You can follow the tutorial at [Tutorial: Configure a CodeBuild-hosted Buildkite runner](sample-runner-buildkite.md) to create a Buildkite webhook manually in the Buildkite console.
## Can I use CloudFormation to create Buildkite webhooks?
CloudFormation is not currently supported for Buildkite runner webhooks, as Buildkite requires webhooks to be created manually using their console.
## Which regions support using a CodeBuild-hosted Buildkite runner?
CodeBuild-hosted Buildkite runners are supported in all CodeBuild regions. For more information about AWS Regions where CodeBuild is available, see [AWS Services by Region](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/).
# Tutorial: Configure a CodeBuild-hosted Buildkite runner
This tutorial shows you how to configure your CodeBuild projects to run Buildkite jobs. For more information about using Buildkite with CodeBuild see [Self-managed Buildkite runner in AWS CodeBuild](buildkite-runner.md).
To complete this tutorial, you must first:
+ Have access to a Buildkite organization. For more information about setting up a Buildkite account and organization, you can follow this [ Getting Started Tutorial](https://buildkite.com/docs/pipelines/getting-started).
+ Create a Buildkite pipeline, cluster, and queue configured to use self-hosted runners. For more information about setting up these resources, you can reference the [ Buildkite Pipeline Setup Tutorial](https://buildkite.com/docs/pipelines/create-your-own).
![\[Build project in Buildkite\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-first.png)
## Step 1: Generate a Buildkite agent token
In this step, you will generate an agent token within Buildkite that will be used to authenticate the CodeBuild self-hosted runners. For more information about this resource, see [Buildkite Agent Tokens](https://buildkite.com/docs/agent/v3/tokens).
**To generate a Buildkite agent token**
1. In your Buildkite cluster, choose **Agent Tokens**, and then choose **New Token**.
1. Add a description to the token and click **Create Token**.
1. Save the agent token value, as it will be used later during the CodeBuild project setup.
![\[Agent tokens in Buildkite\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-createtoken.png)
## Step 2: Create a CodeBuild project with a webhook
**To create a CodeBuild project with a webhook**
1. Open the AWS CodeBuild console at [https://console.aws.amazon.com/codesuite/codebuild/home](https://console.aws.amazon.com/codesuite/codebuild/home).
1. Create a self-hosted build project. For information, see [Create a build project (console)](create-project.md#create-project-console) and [Run a build (console)](run-build-console.md).
+ In **Project configuration**, select **Runner project**. In **Runner**:
+ For **Runner provider**, choose **Buildkite**.
+ For **Buildkite agent token**, choose **Create a new agent token by using the create secret page**. You will be prompted to create a new secret in AWS Secrets Manager with a secret value equal to the Buildkite agent token you generated above.
+ (Optional) If you would like to use CodeBuild managed credentials for your job, select your job’s source repository provider under **Buildkite source credential options** and verify that credentials are configured for your account. Additionally, verify that your Buildkite pipeline uses **Checkout using HTTPS**.
**Note**
Buildkite requires source credentials within the build environment in order to pull your job’s source. See [Authenticating Buildkite to a Private Repository](#sample-runner-buildkite-config) for available source credential options.
+ (Optional) In **Environment**:
+ Choose a supported **Environment image** and **Compute**.
Note that you have the option to override the image and instance settings by using a label in your Buildkite YAML steps. For more information, see [Step 4: Update your Buildkite pipeline steps](#sample-runner-buildkite-update-pipeline).
+ (Optional) In **Buildspec**:
+ Your buildspec will be ignored by default unless `buildspec-override: "true"` is added as a label. Instead, CodeBuild will override it to use commands that will set up the self-hosted runner.
**Note**
CodeBuild does not support buildspec files for Buildkite self-hosted runner builds. For inline buildspecs, you will need to enable [ git-credential-helper](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) in your buildspec if you have configured CodeBuild managed source credentials
1. Continue with the default values and then choose **Create build project**.
1. Save the **Payload URL** and **Secret** values from the **Create Webhook** popup. Either follow the instructions in the popup to create a new Buildkite organization webhook or continue to the next section.
## Step 3: Create a CodeBuild webhook within Buildkite
In this step, you will use the **Payload URL** and **Secret** values from the CodeBuild webhook to create a new webhook within Buildkite. This webhook will be used to trigger builds within CodeBuild when a valid Buildkite job starts.
**To create a new webhook in Buildkite**
1. Navigate to your Buildkite organization’s **Settings** page.
1. Under **Integrations**, select **Notification Services**.
1. Choose **Add** next to the **Webhook** box. In the **Add Webhook Notification** page, use the following configuration:
1. Under **Webhook URL**, add the saved **Payload URL** value.
1. Under **Token**, verify that **Send the token as X-Buildkite-Token** is selected. Add your webhook **Secret** value to the **Token** field.
1. Under , verify that **Send the token as X-Buildkite-Token** is selected. Add your webhook **Secret** value to the **Token** field.
1. Under **Events**, select the `job.scheduled` webhook event.
1. (Optional) Under **Pipelines**, you can optionally choose to only trigger builds for a specific pipeline.
1. Choose **Add Webhook Notification**.
## Step 4: Update your Buildkite pipeline steps
In this step, you will update your Buildkite pipeline’s steps in order to add necessary labels and optional overrides. For the full list of supported label overrides, see [Label overrides supported with the CodeBuild-hosted Buildkite runner](buildkite-runner-update-labels.md).
**Update your pipeline steps**
1. Navigate to your Buildkite pipeline steps page by selecting your Buildkite pipeline, choosing **Settings**, and then choosing **Steps**.
If you haven’t already, choose **Convert to YAML steps**.
![\[Steps to update YAML.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-steps.png)
1. At a minimum, you will need to specify a [ Buildkite agent tag ](https://buildkite.com/docs/agent/v3/cli-start#agent-targeting) referencing the name of your CodeBuild pipeline. The project name is needed to link the AWS-related settings of your Buildkite job to a specific CodeBuild project. By including the project name in the YAML, CodeBuild is allowed to invoke jobs with the correct project settings.
```
agents:
project: "codebuild-"
```
The following is an example of Buildkite pipeline steps with just the project label tag:
```
agents:
project: "codebuild-myProject"
steps:
- command: "echo \"Hello World\""
```
You can also override your image and compute type in the label. See [Compute images supported with the CodeBuild-hosted Buildkite runner](buildkite-runner-update-yaml.images.md) for a list of available images. The compute type and image in the label will override the environment settings on your project. To override your environment settings for a CodeBuild EC2 or Lambda compute build, use the following syntax:
```
agents:
project: "codebuild-"
image: "-"
instance-size: ""
```
The following is an example of Buildkite pipeline steps with image and instance size overrides:
```
agents:
project: "codebuild-myProject"
image: "arm-3.0"
instance-size: "small"
steps:
- command: "echo \"Hello World\""
```
You can override the fleet used for your build in the label. This will override the fleet settings configured on your project to use the specified fleet. For more information, see [ Run builds on reserved capacity fleets ](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html).
To override your fleet settings for an Amazon EC2 compute build, use the following syntax:
```
agents:
project: "codebuild-"
fleet: ""
```
To override both the fleet and the image used for the build, use the following syntax:
```
agents:
project: "codebuild-"
fleet: ""
image: "-"
```
The following is an example of Buildkite pipeline steps with fleet and image overrides:
```
agents:
project: "codebuild-myProject"
fleet: "myFleet"
image: "arm-3.0"
steps:
- command: "echo \"Hello World\""
```
1. You can choose to run inline buildspec commands during the self-hosted Buildkite runner build (see [Run buildspec commands for the INSTALL, PRE\$1BUILD, and POST\$1BUILD phases](sample-runner-buildkite-buildspec.md) for more details). To specify that the CodeBuild build should run buildspec commands during your Buildkite self-hosted runner build, use the following syntax:
```
agents:
project: "codebuild-"
buildspec-override: "true"
```
The following is an example of a Buildkite pipeline with a buildspec override:
```
agents:
project: "codebuild-myProject"
buildspec-override: "true"
steps:
- command: "echo \"Hello World\""
```
1. Optionally, you can provide labels outside of those that CodeBuild supports. These labels will be ignored for the purpose of overriding attributes of the build, but will not fail the webhook request. For example, adding `myLabel: “testLabel"` as a label will not prevent the build from running.
## Step 5: Review your results
Whenever a Buildkite job is started in your pipeline, CodeBuild will receive a `job.scheduled` webhook event through the Buildkite webhook. For each job in your Buildkite build, CodeBuild will start a build to run an ephemeral Buildkite runner. The runner is responsible for executing a single Buildkite 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 Buildkite pipeline and select the most recent build (you can trigger a new build by choosing **New Build**). Once the associated CodeBuild build for each of your jobs starts and picks up the job, you should see logs for the job within the Buildkite console
![\[Review results.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-log.png)
## Authenticating Buildkite to a Private Repository
If you have a private repository configured within your Buildkite pipeline, Buildkite requires [additional permissions within the build environment](https://buildkite.com/docs/agent/v3/github-ssh-keys) to pull the repository, as Buildkite does not vend credentials to self-hosted runners to pull from private repositories. In order to authenticate the Buildkite self-hosted runner agent to your external private source repository, you can use one of the following options.
**To authenticate with CodeBuild**
CodeBuild offers managed credentials handling for Supported source types. In order to use CodeBuild source credentials to pull your job’s source repository, you can use the following steps:
1. In the CodeBuild console, navigate to **Edit project** or create a new CodeBuild project using the steps in [Step 2: Create a CodeBuild project with a webhook](#sample-runner-buildkite-create-project).
1. Under **Buildkite source credential options**, select your job’s source repository provider.
1. If you would like to use account-level CodeBuild credentials, verify that they are configured correctly. Additionally, if your project has an inline buildspec configured, verify that [ git-credential-helper ](https://docs.aws.amazon.com/codebuild/latest/userguide/build-spec-ref.html#build-spec.env.git-credential-helper) is enabled.
1. If you would like to use project level CodeBuild credentials, select **Use override credentials for this project only** and set up credentials for your project.
1. In your Buildkite pipeline settings, navigate to **Repository Settings**. Set your source repository checkout settings to **Checkout using HTTPS**
![\[Review results.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-repo-https.png)
**To authenticate with Buildkite secrets**
Buildkite maintains an [ ssh-checkout plugin](https://github.com/buildkite-plugins/git-ssh-checkout-buildkite-plugin) which can be used to authenticate the self-hosted runner to an external source repository using an ssh key. The key value is stored as a [Buildkite secret](https://buildkite.com/docs/pipelines/security/secrets/buildkite-secrets) and fetched automatically by the Buildkite self-hosted runner agent when attempting to pull a private repository. In order to configure the ssh-checkout plugin for your Buildkite pipeline, you can use the following steps:
1. Generate a private and public ssh key using your email address e.g. `ssh-keygen -t rsa -b 4096 -C "myEmail@address.com"`
1. Add the public key to your private source repository. For example, you can follow [this guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) to add a key to a GitHub account.
1. Add a [ new SSH key secret ](https://buildkite.com/docs/pipelines/hosted-agents/code-access#private-repositories-with-other-providers-add-the-ssh-key-secret) to your Buildkite cluster. Within your Buildkite cluster, select **Secrets** → **New Secret**. Add a name for you secret in the **Key** field and add your private SSH key into the **Value** field:
![\[Review results.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-secret.png)
1. Within your Buildkite pipeline, navigate to your repository settings and set checkout to use **SSH**.
![\[Review results.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-repo.png)
1. Update your pipeline YAML steps to use the `git-ssh-checkout` plugin. For example, the following pipeline YAML file uses the checkout action with the above Buildkite secret key:
```
agents:
project: "codebuild-myProject"
steps:
- command: "npm run build"
plugins:
- git-ssh-checkout#v0.4.1:
ssh-secret-key-name: 'SOURCE_SSH_KEY'
```
1. When running a Buildkite self-hosted runner job within CodeBuild, Buildkite will now automatically use your configured secret value when pulling your private repository
## Runner configuration options
You can specify the following environment variables in your project configuration to modify the setup configuration of your self-hosted runners:
+ `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`: CodeBuild will fetch the secret value configured as the value of this environment variable from AWS Secrets Manager in order to register the Buildkite self-hosted runner agent. This environment variable must be of type `SECRETS_MANAGER`, and the value should be the name of your secret in Secrets Manager. A Buildkite agent token environment variable is required for all Buildkite runner projects.
+ `CODEBUILD_CONFIG_BUILDKITE_CREDENTIAL_DISABLE`: By default, CodeBuild will load account or project level source credentials into the build environment, as these credentials are used by the Buildkite agent to pull the job’s source repository. To disable this behavior, you can add this environment variable to your project with the value set to `true`, which will prevent source credentials from being loaded into the build environment.
# Run buildspec commands for the INSTALL, PRE\$1BUILD, and POST\$1BUILD phases
By default, CodeBuild ignores any buildspec commands when running a self-hosted Buildkite runner build. To run buildspec commands during the build,
```
buildspec-override: "true"
```
can be added as a suffix to the label:
```
agents:
project: "codebuild-"
buildspec-override: "true"
```
By using this command, CodeBuild will create a folder called `buildkite-runner` in the container's primary source folder. When the Buildkite runner starts during the `BUILD` phase, the runner will run in the `buildkite-runner` directory.
There are several limitations when using a buildspec override in a self-hosted Buildkite build:
+ The Buildkite agent requires that source credentials exist within the build environment to pull the job’s source repository. If you use CodeBuild source credentials for authentication, you will need to enable `git-credential-helper` in your buildspec. For example, you can use the following buildspec to enable `git-credential-helper` for your Buildkite builds:
```
version: 0.2
env:
git-credential-helper: yes
phases:
pre_build:
commands:
- echo "Hello World"
```
+ CodeBuild will not run buildspec commands during the `BUILD` phase, as the self-hosted runner runs in the `BUILD` phase.
+ CodeBuild does not support buildspec files for Buildkite runner builds. Only inline buildspecs are supported for Buildlkite self-hosted runners
+ If a build command fails in the `PRE_BUILD` or `INSTALL` phase, CodeBuild will not start the self-hosted runner and the Buildkite job will need to be cancelled manually.
# Setting up a Buildkite runner programmatically
In order to configure a Buildkite runner project programatically, you will need to configure the following resources:
**To create a Buildkite runner programmatically**
1. Create a Buildkite agent token and save the token in plaintext within AWS Secrets Manager.
1. Set up a CodeBuild project with your preferred configuration. You will need to configure the following additional attributes:
1. An environment value with name `CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN`, type `SECRETS_MANAGER`, and a value equal to the Buildkite agent token associated with your Buildkite cluster.
1. Source type equal to `NO_SOURCE`
1. Permissions to access the secret created in step 1 in your project’s service role
For example, you can use the following command to create a valid Buildkite runner project through the CLI:
```
aws codebuild create-project \
--name buildkite-runner-project \
--source "{\"type\": \"NO_SOURCE\",\"buildspec\":\"\"}" \
--environment "{\"image\":\"aws/codebuild/amazonlinux-x86_64-standard:5.0\",\"type\":\"LINUX_CONTAINER\",\"computeType\":\"BUILD_GENERAL1_MEDIUM\",\"environmentVariables\":[{\"name\":\"CODEBUILD_CONFIG_BUILDKITE_AGENT_TOKEN\",\"type\":\"SECRETS_MANAGER\",\"value\":\"\"}]}" \
--artifacts "{\"type\": \"NO_ARTIFACTS\"}" \
--service-role
```
1. Create a Buildkite runner webhook on the project created in step 2. You will need to use the following configuration options when creating the webhook:
1. **build-type** should be equal to `RUNNER_BUILDKITE_BUILD`
1. A filter with type `EVENT` and a pattern equal to `WORKFLOW_JOB_QUEUED`
For example, you can use the following command to create a valid Buildkite runner webhook through the CLI:
```
aws codebuild create-webhook \
--project-name buildkite-runner-project \
--filter-groups "[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"}]]" \
--build-type RUNNER_BUILDKITE_BUILD
```
1. Save the **Payload URL** and **Secret** values returned by the `create-webhook` call and use the credentials to create a webhook within the Buildkite console. You can reference Step 3: Create a CodeBuild webhook within Buildkite in [Tutorial: Configure a CodeBuild-hosted Buildkite runner](sample-runner-buildkite.md) for a guide on how to set up this resource.
# Troubleshoot the webhook for failed builds or a hanging job
**Issue: **
The webhook you set up in [Tutorial: Configure a CodeBuild-hosted Buildkite runner](sample-runner-buildkite.md) isn't working or your workflow job is hanging in Buildkite.
**Possible causes: **
+ Your webhook **job.scheduled** event might be failing to trigger a build. Review the **Response** logs to view the response or error message.
+ Your CodeBuild build fails before starting the Buildkite self-hosted runner agent to handle your job.
**Recommended solutions: **
To debug failed Buildkite webhook events:
1. In your Buildkite organization settings, navigate to **Notification Services**, select your CodeBuild webhook, and then find the **Request Log**.
1. Find the `job.scheduled` webhook event associated with your stuck Buildkite job. You can use the job ID field within the webhook payload to correlate the webhook event to your Buildkite job.
1. Select the **Response** tab and check the response body. Verify that the **Response** status code is `200` and the **Response** body doesn’t contain any unexpected messages.
![\[Response for the webhook.\]](http://docs.aws.amazon.com/codebuild/latest/userguide/images/buildkite-request.png)
# Troubleshoot the webhook permission issues
**Issue: **
The Buildkite job fails to checkout the job's source repository due to permission issues.
**Possible causes: **
+ CodeBuild does not have sufficient permissions to checkout the job's source repository.
+ The pipeline's repository settings are set to check out using SSH for CodeBuild managed credentials.
**Recommended solutions: **
+ Verify that CodeBuild has sufficient permissions configured to check out the job's source repository. Additionally, verify that your CodeBuild project's service role has sufficient permissions to access the configured source permission option.
+ Verify that your Buildkite pipeline is configured to use checkout using HTTPS if you are using CodeBuild managed source repository credentials.
# Label overrides supported with the CodeBuild-hosted Buildkite runner
In your Buildkite pipeline steps agent tag labels, you can provide a variety of label overrides that modify your self-hosted runner build. Any builds not recognized by CodeBuild will be ignored but will not fail your webhook request. For example, the following workflow YAML includes overrides for image, instance size, fleet, and the buildspec:
```
agents:
queue: "myQueue"
steps:
- command: "echo \"Hello World\""
agents:
project: "codebuild-myProject"
image: "{{matrix.os}}"
instance-size: "{{matrix.size}}"
buildspec-override: "true"
matrix:
setup:
os:
- "arm-3.0"
- "al2-5.0"
size:
- "small"
- "large"
```
`project:codebuild-` (required)
+ Example: `project: "codebuild-myProject"`
+ Required for all Buildkite pipeline step configurations. ** should be equal to the name of the project for which the self-hosted runner webhook is configured.
`queue: ""`
+ Example: `queue: ""`
+ Used to route Buildkite jobs to a specific queue. See the [ Buildkite Agent Queue Tag ](https://buildkite.com/docs/agent/v3/cli-start#the-queue-tag) for more information.
`image: "-"`
+ Example: `image: "arm-3.0"`
+ Overrides the image and environment type used when starting the self-hosted runner build with a curated image. To learn about supported values, see [Compute images supported with the CodeBuild-hosted Buildkite runner](buildkite-runner-update-yaml.images.md).
1. To override the image and environment type used with a custom image, use `image: "custom--"`
1. Example:
```
image:
"custom-arm-public.ecr.aws/codebuild/amazonlinux-aarch64-standard:3.0"
```
**Note**
If the custom image resides in a private registry, you must configure the appropriate registry credentials in your CodeBuild project.
`instance-size: ""`
+ Example: `instance-size: "medium"`
+ Overrides the instance type used when starting the self-hosted runner build. To learn about supported values, see [Compute images supported with the CodeBuild-hosted Buildkite runner](buildkite-runner-update-yaml.images.md).
`fleet: ""`
+ Example: `fleet: "myFleet"`
+ Overrides the fleet settings configured on your project to use the specified fleet. For more information, see [ Run builds on reserved capacity fleets ](https://docs.aws.amazon.com/codebuild/latest/userguide/fleets.html).
`buildspec-override: ""`
+ Example: `buildspec-override: "true"`
+ Allows the build to run buildspec commands in the `INSTALL`, `PRE_BUILD`, and `POST_BUILD` phases if set to `true`.
# Compute images supported with the CodeBuild-hosted Buildkite runner
In the label you configured in [Self-managed Buildkite runner in AWS CodeBuild](buildkite-runner.md), you can override your Amazon EC2 environment settings by using the values in the first three columns. CodeBuild provides the following Amazon EC2 compute images. For more information about
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/buildkite-runner-update-yaml.images.html)
In addition, you can override your Lambda environment settings by using the following values. For more information about CodeBuild Lambda compute, see [Run builds on AWS Lambda compute](lambda.md). CodeBuild supports the following Lambda compute images:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codebuild/latest/userguide/buildkite-runner-update-yaml.images.html)
For more information, see [Build environment compute modes and types](build-env-ref-compute-types.md) and [Docker images provided by CodeBuild](build-env-ref-available.md).