Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Use GitHub Actions syntax in a buildspec in Amazon CodeBuild

You can use a CodeBuild-managed action runner to run GitHub Actions within CodeBuild. This can be done by adding steps to any phase in your buildspec file.

CodeBuild buildspecs support a list of sequential GitHub Action steps which run in a separate phase from CodeBuild commands. These GitHub Actions integrate with CodeBuild’s existing features, which include dependency caching, batch builds, access to Amazon Secrets Manager, and more.

How do I get started with using a GitHub Action in my buildspec?

The high-level steps to use a GitHub Action in your buildspec are as follows:

Which GitHub Actions can I use in my buildspec?

You can use any action available in the GitHub Marketplace that doesn't conflict with these limitations.

Can I use source providers other than GitHub when using GitHub Actions in my buildspec?

Yes, but connecting to GitHub is still required to authenticate with GitHub and access GitHub Actions. For more information, see GitHub and GitHub Enterprise Server access token.

Why do I need to connect to GitHub as a source provider in order to use GitHub Actions in my buildspec?

In order to use GitHub Actions in your buildspec, the source must be downloaded on a build compute. Anonymous downloads will be rate limited, so by connecting to GitHub, it can help ensure consistent access.

How much does it cost to use GitHub Actions in my buildspec?

Using GitHub Actions in your buildspec is supported at no additional cost.

Which regions support using GitHub Actions in my buildspec?

Using GitHub Actions in your buildspec is supported in all CodeBuild regions. For more information about Amazon Web Services Regions where CodeBuild is available, see Amazon Services by Region.

Best practices for using GitHub Actions in your buildspec

GitHub Actions are open source, built and maintained by the community. We follow the shared responsibility model and consider GitHub Actions source code as customer data for which you are responsible. GitHub Actions can be granted access to secrets, repository tokens, source code, and account links. Make sure you are confident in the trustworthiness and security of the GitHub Actions you plan to run.

More specific guidance and security best practices for GitHub Actions:

Limitations of using GitHub Actions in your buildspec in CodeBuild

GitHub Action runner buildspec reference

This topic contains the buildspec reference for GitHub Action runner properties.

steps

Optional sequence. Steps are used to run commands and actions in CodeBuild. For more information, see Use GitHub Actions syntax in a buildspec in Amazon CodeBuild.

Each build step contains the following properties.

The following is an example using the Super-Linter GitHub Action:

version: 0.2
phases:
  build:
    steps:
      - name: Lint Code Base
        uses: github/super-linter@v5
        env:
          VALIDATE_ALL_CODEBASE: true
          USE_FIND_ALGORITHM: true
          FILTER_REGEX_INCLUDE: '/github/workspace/buildspec.yml'

GitHub Action syntax samples with Amazon CodeBuild

These groups of samples can be used to experiment with GitHub Actions in your buildspec in CodeBuild.

Super-Linter GitHub Action sample

This sample demonstrates how to add the Super-Linter GitHub Action to a CodeBuild project. The Super-Linter action inspects code, finds areas where the code has errors, formatting issues, and suspicious constructs, and then outputs the results to the CodeBuild console.

You can add the Super-Linter GitHub Action to your CodeBuild project by updating the phase section of your buildspec file.

version: 0.2
phases:
  build:
    steps:
      - name: Lint Code Base
        uses: github/super-linter@v5
        env:
          VALIDATE_ALL_CODEBASE: true

The Super-Linter logs will look similar to the following:

/github/workspace/hello-world/app.js:3:13: Extra semicolon.
/github/workspace/hello-world/app.js:9:92: Trailing spaces not allowed.
/github/workspace/hello-world/app.js:21:7: Unnecessarily quoted property 'body' found.
/github/workspace/hello-world/app.js:31:1: Expected indentation of 2 spaces but found 4.
/github/workspace/hello-world/app.js:32:2: Newline required at end of file but not found.

Batch build graph sample

The following example defines a build graph that creates a dependency chain and runs commands using steps. In this example, build1 runs first because it has no dependencies. Since build2 has a dependency on build1, so build2 runs after build1 completes. For information, see Build graph.

version: 0.2
batch:
  fast-fail: false
  build-graph:
    - identifier: build1
      env:
        variables:
          BUILD_ID: build1
      ignore-failure: false
    - identifier: build2
      env:
        variables:
          BUILD_ID: build2
      depend-on:
        - build1

phases:
  build:
    steps:
      - run: echo $BUILD_ID

Amazon CodeGuru Reviewer sample

Amazon CodeGuru Reviewer finds issues in your Java and Python code and recommends how to remediate them. The following example uses CodeGuru Reviewer to provide full repository analysis code reviews. These code reviews scan all the code in a specified branch. For information, see Create code reviews with GitHub Actions in the Amazon CodeGuru Reviewer User Guide.

version: 0.2
phases:
  build:
    steps:
        - name: Amazon CodeGuru Reviewer Scanner
          if: ${{ always() }}
          uses: aws-actions/codeguru-reviewer@v1.1
          with:
            s3_bucket: codeguru-reviewer-user

artifacts:
  files:
    - codeguru-results.sarif.json

The logs will look similar to the following:

INFO CodeReview created with arn=arn:aws:codeguru-reviewer:region:account-id:association:id:code-review:RepositoryAnalysis-job for job=job
INFO SARIF persisted to /github/workspace/codeguru-results.sarif.json
INFO Amazon CodeGuru Reviewer job execution completed

After the Amazon CodeGuru Reviewer job is complete, a sarif report is generated as CodeBuild artifact. For information, see Full repository analysis in the Amazon CodeGuru Reviewer User Guide.

Amazon Secrets Manager sample

Amazon Secrets Manager helps you manage, retrieve, and rotate database credentials, application credentials, OAuth tokens, API keys, and other secrets throughout their lifecycles. The following example defines a secret using Secrets Manager and runs commands using steps. For information, see What is Amazon Secrets Manager? in the Amazon Secrets Manager User Guide.

version: 0.2
env:
  secrets-manager:
    SECRET_VALUE: "arn:aws:secretsmanager:us-east-1:xxxx:secret:/secret-l3IJg9:my_super_secret_key"
phases:
  build:
    steps:
      - run: echo $SECRET_VALUE

The logs will look similar to the following:

echo $SECRET_VALUE
env:
  SECRET_VALUE: ***
***

Environment variable sample

The following example defines environment variables under the env sequence. A S3_BUCKET variable is defined in the buildspec and assigned <bucket-name> as its value. This variable is referenced in the if conditional like a regular environment variable by using the dollar sign ($) to access the GitHub Action env context. For more information, see env sequence.

version: 0.2
env:
  variables:
    S3_BUCKET: "<bucket-name>"
phases:
  build:
    steps:
      - if: ${{ env.S3_BUCKET == '<bucket-name>' }}
        run: echo "S3 bucket is $S3_BUCKET"

The logs will look similar to the following:

echo "S3 bucket is $S3_BUCKET"
env:
  S3_BUCKET: my-s3-bucket
S3 bucket is my-s3-bucket

Exported environment variable sample

Exported environment variables are used in conjunction with CodePipeline to export environment variables from the current build stage to subsequent stages in the pipeline. The following example defines an exported environment variable under the env sequence named MY_VARIABLE and writes to the GITHUB_ENV environment file.

version: 0.2
env:
  exported-variables:
    - MY_VARIABLE
phases:
  build:
    steps:
      - run: echo "MY_VARIABLE=my-value" >> $GITHUB_ENV

For more information, see ExportedEnvironmentVariable in the Amazon CodeBuild API Reference.