GHA.md

GitHub Actions

The Buildkite Migration tool's currently supported (✅), partially supported (⚠️) and unsupported (❌) properties in translation of GitHub Action workflows to Buildkite pipelines are listed below.

Note

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

A core principle of the Buildkite's architecture is that secrets and sensitive data are decoupled from the core SaaS platform and remains on customer/tenant environments and are not seen or stored.

The utilisation of a secret storage service such as HashiCorp Vault or AWS Secrets Manager, accompanied by the use of their respective plugin can be configured to read and utilize secrets within Buildkite pipelines. Additionally, the S3 Secrets Buildkite plugin can be installed within a Buildkite agent - this service automatically included within Elastic CI Stack for AWS setups to expose secrets from S3 into the jobs of a Buildkite pipelines' builds.

Concurrency (concurrency)

Key	Supported?	Notes
concurrency	❌	Buildkite concurrency groups don't apply to whole pipelines but 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 (defaults)

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

Environment (env)

Key	Supported?	Notes
env	✅	Environment variables that are defined at the top of a workflow will be transition to build level environment variables in the generated Buildkite pipeline

Jobs (jobs)

Note

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

Key	Supported?	Notes
jobs.<id>.concurrency	⚠️	The group name inside a concurrency definition inside a job maps to the concurrency_group key available within Buildkite. The cancel-in-progress optional value maps to the Buildkite pipeline setting of Cancel Intermediate Builds. Buildkite also allows a upper limit on how much jobs are created through a single step definition with the concurrency key: which is set as 1 by default (there isn't a translatable key within a GitHub Action workflow).
jobs.<id>.env	✅	Environment variables defined within the context of each of a workflow's jobs are transitioned to step level environment variables.
jobs.<id>.runs-on	✅	This attribute is mapped to the agent targeting tag runs-on. Jobs that target custom tag names will have a queue target of default.
jobs.<id>.steps	✅	Steps that make up a particular action's job.
jobs.<id>.steps.env	✅	Environment variables that are defined at step level are translated as a variable definition within the commands of a Buildkite command step.
jobs.<id>.steps.run	✅	The commands (less 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 command step.
jobs.<id>.steps.strategy	✅	Allows for the conversion of a step's strategy (matrix) to create multiple jobs of a combination of values.
jobs.<id>.steps.strategy.matrix	✅	A matrix key inside of a step's strategy will be translated to a Buildkite build matrix.
jobs.<id>.steps.strategy.matrix.include	✅	Key/value pairs to add in the generated matrix's combinations.
jobs.<id>.steps.strategy.matrix.exclude	✅	Key/value pairs to exclude in the generated matrix's combinations (skip).
jobs.<id>.steps.uses	❌	uses defines a separate action to use within the context of a action's job, and is currently not supported.

Name (name)

Key	Supported?	Notes
name	❌	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, it's name is set through the UI when first creating the pipeline - and can be altered within its pipeline settings, or via the REST or GraphQL APIs.

On (on)

Key	Supported?	Notes
on	❌	The on key allows for triggering a GitHub Action workflow. In Buildkite pipelines - this capability is defined within a trigger step - where utilized within a pipeline, will create a build on the specified pipeline with additional properties.

Permissions (permissions)

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

Run Name (run-name)

Key	Supported?	Notes
run-name	❌	Build messages in Buildkite are set as the BUILDKITE_MESSAGE environment variable (commit message from source control). Build messages are settable in manual build creation, and via both REST and GraphQL APIs.