# 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).