GitHub Actions

The Buildkite migration tool helps you convert your GitHub Actions workflows into Buildkite pipelines. This page lists the Buildkite migration tool's supported, partially supported, and unsupported GitHub Actions keys when translating from GitHub Actions workflows to Buildkite pipelines.

For any partially supported and unsupported Keys listed in the tables on this page, you should follow the instructions provided in their relevant Notes, for details on how to successfully complete their translation into a working Buildkite pipeline.

The Buildkite migration tool currently does not support GitHub secrets stored within GitHub organizations or repositories (such as {{ secrets.FOO }}).

A core principle of Buildkite's self-hosted (hybrid) architecture is that secrets and sensitive data stay in the customer's environments, which in turn are decoupled from and not seen by the core Buildkite Pipelines SaaS control plane.

Using a secret storage service such as Hashicorp Vault or AWS Secrets Manager, along with their respective plugin, can be configured to read and utilize secrets within Buildkite pipelines. The S3 Secrets Buildkite plugin can be installed within a Buildkite agent—this service is automatically included within Elastic CI Stack for AWS setups to expose secrets from S3 into the jobs of a Buildkite pipeline's builds.

Using the Buildkite migration tool with GitHub Actions

To start converting your GitHub Actions workflow into Buildkite Pipelines format:

Open the Buildkite migration interactive web tool in a new browser tab.
Ensure GitHub Actions is selected at the top of the left panel.
Copy your GitHub Actions workflow configuration and paste it into the left panel.
Select Convert to reveal the translated pipeline configuration in the Buildkite Pipeline panel.

For example, when converting the following example GitHub Actions workflow configuration:

name: CI

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: '18'

    - name: Install dependencies
      run: npm install

The Buildkite migration tool should translate this to the following output:

---
steps:
- commands:
  - "# action actions/checkout@v4 is not necessary in Buildkite"
  - echo '~~~ Install dependencies'
  - npm install
  plugins:
  - docker#v5.10.0:
      image: node:18
  agents:
    runs-on: ubuntu-latest
  label: ":github: build"
  key: build
  branches: main

The Buildkite migration tool interface should look similar to this:

Converting a GitHub Actions pipeline in Buildkite migration tool's web UI

You might need to adjust the converted Buildkite pipeline output to ensure it is consistent with the step configuration conventions used in Buildkite Pipelines.

Remember that not all the features of GitHub Actions can be fully converted to the Buildkite Pipelines format. See the following sections to learn more about the compatibility, workarounds, and limitation of converting GitHub Actions workflows to Buildkite pipelines.

Concurrency

Key	Supported	Notes
Key	`concurrency`	Supported	No	Notes	Buildkite Pipelines' concurrency groups don't apply to whole pipelines but rather to individual steps, so there is no direct translation of this configuration. Refer to the support of the job-level configuration for more information: `jobs.<id>.concurrency`.

Defaults

Key	Supported	Notes
Key	`defaults.run`	Supported	No	Notes	Buildkite pipeline definitions allow for common pipeline configurations to be applied with YAML anchors, as well as setting up customised agent and job lifecycle hooks.

Environment

Key	Supported	Notes
Key	`env`	Supported	Yes	Notes	Environment variables that are defined at the top of a workflow will be translated to build-level environment variables in the generated Buildkite pipeline.

Jobs

When Buildkite pipelines are built, each command step inside the pipeline is ran as a job that will be distributed and assigned to the matching agents meeting their specific queue and tag targeting. Each job is run within its own separate environment, with potentially different environment variables (for example, those defined at the step level) and is not guaranteed to run on the same agent depending on targeting rules and the agent fleet setup.

Key	Supported	Notes
Key	`jobs.<id>.concurrency`	Supported	Partially	Notes	The `group` name inside a `concurrency` definition inside of a job maps to the `concurrency_group` key available within Buildkite Pipelines. The `cancel-in-progress` optional value maps to the Buildkite pipeline setting of Cancel Intermediate Builds. Buildkite Pipelines also allow setting an upper limit on how many jobs are created through a single step definition with the `concurrency` key which is set as `1` by default (there isn't a translatable counterpart to the "key" parameter within a GitHub Action workflow).
Key	`jobs.<id>.env`	Supported	Yes	Notes	Environment variables defined within the context of each of a workflow's `jobs` are translated to step-level environment variables.
Key	`jobs.<id>.runs-on`	Supported	Yes	Notes	This attribute is mapped to the agent targeting tag `runs-on`. Jobs that target custom `tag` names will have a `queue` target of `default`.
Key	`jobs.<id>.steps`	Supported	Yes	Notes	Steps that make up a particular action's `job`.
Key	`jobs.<id>.steps.env`	Supported	Yes	Notes	Environment variables that are defined at `step` level are translated as a variable definition within the `commands` of a command step.
Key	`jobs.<id>.steps.run`	Supported	Yes	Notes	The commands (must be shorter than 21,000 characters) that make up a particular job. Each `run` is translated to a separate command inside of the output `commands` block of its generated Buildkite Pipelines command step.
Key	`jobs.<id>.steps.strategy`	Supported	Yes	Notes	Allows for the conversion of a step's `strategy` (matrix) to create multiple jobs from a combination of values.
Key	`jobs.<id>.steps.strategy.matrix`	Supported	Yes	Notes	A `matrix` key inside of a step's `strategy` will be translated to a Buildkite build matrix.
Key	`jobs.<id>.steps.strategy.matrix.include`	Supported	Yes	Notes	Key-value pairs to add as combinations (using `adjustments.with`) to the generated build matrix's combinations.
Key	`jobs.<id>.steps.strategy.matrix.exclude`	Supported	Yes	Notes	Key-value pairs to exclude from being processed (using `skip`) from the generated build matrix's combinations.
Key	`jobs.<id>.steps.uses`	Supported	No	Notes	`uses` defines a separate action to use within the context of a GitHub Action's job. This key currently isn't supported.

Name

Key	Supported	Notes
Key	`name`	Supported	No	Notes	The `name` key sets the name of the action as it will appear in the GitHub repository's Actions tab. When creating a Buildkite pipeline, its name is usually set through the Buildkite interface when a pipeline is first created, and can be altered through the pipeline settings, or using the REST or GraphQL APIs.

On

Key	Supported	Notes
Key	`on`	Supported	No	Notes	The `on` key defines the pipeline trigger in a GitHub Action workflow. In Buildkite Pipelines, this is a Buildkite interface setting in the pipeline's Settings > GitHub page > GitHub Settings section.

Permissions

Key	Supported	Notes
Key	`permissions`	Supported	No	Notes	API Access Tokens can be used within the context of a pipeline's build to interact with various Buildkite resources such as pipelines, artifacts, users, Test Suites, and more. Each access token has a specified set of token scopes that applies to interactions with the REST API, and can be configured with a permission to interact with Buildkite's GraphQL API. The `permissions` key allows for the interaction with commit `statuses`. The Buildkite GitHub App must be added to the respective GitHub organization to allow Buildkite Pipelines to publish commit statuses for builds based on commits and pull requests on pipeline builds and for the statuses to appear based on a build's outcome. The GitHub App can be configured with access to all or a select number of repositories within a GitHub organization.

Run name

Key	Supported	Notes
Key	`run-name`	Supported	No	Notes	Build messages in Buildkite Pipelines are set as the `BUILDKITE_MESSAGE` environment variable (commit message from source control). Build messages can be set in when creating new builds manually, or by using the REST or GraphQL APIs.