diff --git a/Readme.md b/Readme.md index f1b4665a..fcc7c31e 100644 --- a/Readme.md +++ b/Readme.md @@ -1,6 +1,8 @@ # Buildkite Migration tool [![Build status](https://badge.buildkite.com/5db82bf94b2c528cb9723cdd222b60baca00c6328265c8427c.svg)](https://buildkite.com/buildkite/migration-tool) -A tool to help kick start the transition of pipelines from other CI providers to Buildkite. +The Buildkite migration tool serves as a compatibility layer, enabling the conversion of your existing CI configurations into a format compatible with Buildkite's pipeline definitions. + +You can start the translation of your pipelines from other CI providers to Buildkite Pipelines by seeing how workflows from other CI/CD platforms map to the Buildkite Pipelines' concepts and architecture. Rather than serving as a complete automated migration solution, the Buildkite migration tool demonstrates how configurations from these other CI/CD platforms could be structured in a Buildkite pipeline configuration format. ```shell $ buildkite-compat examples/circleci/legacy.yml @@ -96,8 +98,8 @@ Buildkite has its own suggested best practices, these may differ to those from o ## Further Details -Further information on the currently supported attributes of CI provider pipeline translation to Buildkite pipelines can be found below (within the `/docs` directory): +Further information on the currently supported attributes of CI provider pipeline translation to Buildkite pipelines can be found in the official Buildkite Documentation: -- [Bitbucket Pipelines](/docs/Bitbucket.md) -- [CircleCI](/docs/CircleCI.md) -- [GitHub Actions](/docs/GHA.md) +- [GitHub Actions](https://buildkite.com/docs/pipelines/migration/tool/github-actions) +- [CircleCI](https://buildkite.com/docs/pipelines/migration/tool/circleci) +- [Bitbucket Pipelines](https://buildkite.com/docs/pipelines/migration/tool/bitbucket-pipelines) diff --git a/docs/Bitbucket.md b/docs/Bitbucket.md deleted file mode 100644 index 995001b9..00000000 --- a/docs/Bitbucket.md +++ /dev/null @@ -1,170 +0,0 @@ -# Bitbucket Pipelines - -The Buildkite Migration tool's currently supported (✅), partially supported (⚠️) and unsupported (❌) properties in translation of Bitbucket pipelines to Buildkite pipelines are listed below. - -> [!NOTE] -> The Bitbucket Pipeline configuration that is described in the various sections below is specified in the central `bitbucket-pipelines.yml` within a specific Bitbucket workspace [repository](https://support.atlassian.com/bitbucket-cloud/docs/what-is-a-workspace/). In Buildkite - pipeline configuration can be set in a singular `pipeline.yml` within a repository - but can also be set and uploaded dynamically through the use of [Dynamic Pipelines](https://buildkite.com/docs/pipelines/defining-steps#dynamic-pipelines). Additionally, control and governance of Buildkite pipelines can be achieved by the use of [Pipeline Templates](https://buildkite.com/docs/pipelines/templates) to set shared pipeline configuration within a Buildkite organization. - -## Clone (`clone`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `clone` | ⚠️ | Clone options for all steps of a Bitbucket pipeline. The majority of these options should be set on a Buildkite agent itself via [configuration](https://buildkite.com/docs/agent/v3/configuration) of properties such as the clone flags (`git-clone-flags`, `git-clone-mirror-flags` if utilising a Git mirror), fetch flags (`git-fetch-flags`) - or changing the entire checkout process in a customised [plugin](https://buildkite.com/docs/plugins/writing) overriding the default agent `checkout` hook.

Sparse-checkout properties of `code-mode`, `enabled` and `patterns` will be translated to the respective properties within the [sparse-checkout-buildkite-plugin](https://github.com/buildkite-plugins/sparse-checkout-buildkite-plugin).

`clone` properties at the Bitbucket pipeline, if set, have higher precedence over these global properties. | - -## Definitions (`definitions`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `definitions` | ⚠️ | Customised definitions utilised throughout a Bitbucket pipeline. `caches` and `services` are supported for translation within Buildkite Migration tool. | -| `definitions.caches` | ⚠️ | Customised cache definitions that can be applied to specific Bitbucket pipeline steps - inclusive of folders, single file - or multifile cache. Targeted into specific steps with the `pipelines.default.step.caches.` property, and in which the translation will utilise the [cache-buildkite-plugin](https://github.com/buildkite-plugins/cache-buildkite-plugin) that may require further setup/tweaking around specific caching strategies. | -| `definitions.caches.` | ✅ | A customised cache name applicable for one or more steps within a Bitbucket pipeline. | -| `definitions.caches..path` | ✅ | The directory path that is desired to be cached. | -| `definitions.caches..key.files` | ⚠️ | The list (one or more) files that are monitored for changes - and stored once its hash changes between file versions change. If multiple files are specified - multiple cache-plugin definitions are set on the resultant Buildkite command step (differing `manifest` properties between each).

Note this may cause issues if the same folder is being maintained by each cache definition! | -| `definitions.pipeline` | ⚠️ | Pipelines that are exported for re-use within repositories of the same workspace. Like functionality exists within Buildkite as [Pipeline Templates](https://buildkite.com/docs/pipelines/templates). | -| `definitions.services` | ⚠️ | Defined Docker services that are applied within a Bitbucket pipeline. Services defined in a corresponding Bitbucket pipeline step using the `pipelines.default.step.services` property will have its configuration applied with the use of the [docker-compose-buildkite-plugin](https://github.com/buildkite-plugins/docker-compose-buildkite-plugin).

Generated configuration will need to be saved to a `compose.yaml` file within the repository, and the image utilised with the Buildkite command step as `app`.

Refer to the Bitbucket pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/databases-and-service-containers/) for more details on service containers and configuration references.

Authentication based parameters will not be translated to the corresponding Buildkite pipeline if defined. | - -## Export (`export`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `export` | ❌ | Bitbucket Premium option of sharing pipeline configuration between workspaces. Not applicable within Buildkite as an attribute - like functionality exists within [Pipeline Templates](https://buildkite.com/docs/pipelines/templates). | - -## Image (`image`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `image` | ✅ | The container image that is to be applied for each step within a Bitbucket pipeline, utilising the specified image within the [docker-buildkite-plugin](https://github.com/buildkite-plugins/docker-buildkite-plugin). This has lower precedence over per-step `image` configuration (see `pipelines.default.step.image`).

The `aws`, `aws.oidc`, `name`, `username` and `password` sub-properties are supported through the use of the corresponding plugin ([Docker Login](https://github.com/buildkite-plugins/docker-login-buildkite-plugin/) or [ECR](https://github.com/buildkite-plugins/ecr-buildkite-plugin/)). | - -## Options (`options`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `options` | ⚠️ | Customised options utilised throughout a Bitbucket pipeline. The `max-time` and `size` sub-properties are supported for translation within Buildkite Migration tool through to the generated Buildkite command step's `timeout_in_minutes` and agent tag respectfully.

The `docker` sub-property is not supported: and will depend on the agent configuration that the corresponding Buildkite command step is being targeted to run said job has available.

Both supported properties at Bitbucket pipeline [step-level definition](#pipeline-properties-pipelinestypeproperty) will have higher precedences than the two values set at `options` level. | - -## Pipeline Starting Conditions (`pipelines.`) - -> [!NOTE] -> Bitbucket Pipelines allows the configuration of various pipeline start conditions: each supporting different configuration and permissible properties: -> - `branches`: Defines the branch-specific configuration of a Bitbucket pipeline. -> - `custom`: A customised starting condition whereby only manual triggering is allowed. -> - `default`: The default starting configuration of a Bitbucket pipeline if it does not fall into one of the other conditions. -> - `pull_request`: Defines the pull-request specific configuration of a Bitbucket pipeline. -> - `tags`: Defines the tag specific configuration of a Bitbucket pipeline. -> -> For information on each of these individual starting conditions, refer to the reference within the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/#Custom--manual--pipeline-variables). - -### Branches (`pipelines.branches`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines.branches` | ✅ | Application of specific Bitbucket pipeline configuration based for specific branches. Translated to a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps) in the corresponding Buildkite pipeline utilising the `build.branch`/`BUILDKITE_BRANCH` variable. | -| `pipelines.branches.` | ✅ | The branch name/wildcard to apply specific Bitbucket pipeline step configuration within. | -| `pipelines.branches..parallel` | ✅ | Parallel (concurrent step) configuration for a specific branch within a Bitbucket pipeline. View the available parallel [properties](#parallel-pipelinestypeparallel) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel). | -| `pipelines.branches..step` | ✅ | Individual step configuration for a specific branch within a Bitbucket pipeline. See configuration options in this section (`pipelines.default.step.`) for supported/unsupported properties. | -| `pipelines.branches..stage` | ✅ | Stage configuration for a specific branch within a Bitbucket pipeline. View the available stage [properties](#stage-pipelinestypestage) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage). | - -### Custom (`pipelines.custom`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines.custom` | ✅ | Bitbucket pipelines that are only able to be triggered manually. The corresponding Buildkite pipeline is first generated with an [input step](https://buildkite.com/docs/pipelines/input-step) before any command jobs to ensure that triggered builds must be manually processed. | -| `pipelines.custom.` | ✅ | The name of the custom Bitbucket pipeline. | -| `pipelines.custom..import-pipeline.import` | ❌ | The specification of importing a pipeline from within a specific repository defined in top-level `definitions`. Consider using [trigger steps](https://buildkite.com/docs/pipelines/trigger-step) to invoke builds on a specific Buildkite pipeline. | -| `pipelines.custom..parallel` | ✅ | Parallel (concurrent step) configuration for a custom Bitbucket pipeline. View the available parallel [properties](#parallel-pipelinestypeparallel) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel). | -| `pipelines.custom..step` | ✅ | Individual step configuration for a custom Bitbucket pipeline. View the available step [properties](#step-pipelinestypestep) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#The-Step-property). | -| `pipelines.custom..stage` | ✅ | Stage configuration for a custom Bitbucket pipeline. View the available stage [properties](#stage-pipelinestypestage) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage). | -| `pipelines.custom..variables` | ⚠️ | Variable configuration for a custom Bitbucket pipeline. View the available variable [properties](#variables-pipelinesstart-conditionvariables) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/#Custom--manual--pipeline-variables). | - -### Default (`pipelines.default`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines.default` | ✅ | Bitbucket pipeline configuration that does not meet a specific configuration. Additional details can be found on this pipeline type's [documentation](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/#Default) | -| `pipelines.default.parallel` | ✅ | Parallel (concurrent step) configuration for default Bitbucket pipelines. View the available parallel [properties](#parallel-pipelinestypeparallel) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel). | -| `pipelines.default.step` | ✅ | Individual step configuration for default Bitbucket pipelines. View the available step [properties](#step-pipelinestypestep) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#The-Step-property). | -| `pipelines.default.stage` | ✅ | Stage configuration for default Bitbucket pipelines. View the available stage [properties](#stage-pipelinestypestage) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage). | - -### Pull Request (`pipelines.pull_request`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines.pull_request` | ✅ | Application of specific Bitbucket pipeline configuration based for pull requests. Translated to a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps) in the corresponding Buildkite pipeline utilising the `pull_request.id`/`BUILDKITE_PULL_REQUEST` and `build.branch`/`BUILDKITE_BRANCH` variables. | -| `pipelines.pull_request.` | ✅ | The base branch name/wildcard to apply specific Bitbucket pipeline step configuration within. Apply the configuration for all builds with a `**` wildcard. | -| `pipelines.pull_request..parallel` | ✅ | Parallel (concurrent step) configuration for pull request builds of a Bitbucket pipeline. View the available parallel [properties](#parallel-pipelinestypeparallel) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel). | -| `pipelines.pull_request..step` | ✅ | Individual step configuration for pull requests builds within a Bitbucket pipeline. View the available step [properties](#step-pipelinestypestep) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#The-Step-property). | -| `pipelines.default.stage` | ✅ | Stage configuration for pull request builds of a Bitbucket pipelines. View the available stage [properties](#stage-pipelinestypestage) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage). | - -### Tags (`pipelines.tags`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines.tags` | ✅ | Application of specific Bitbucket pipeline configuration based for triggered tag builds. Translated to a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps) in the corresponding Buildkite pipeline utilising the `build.tag`/`BUILDKITE_TAG` variable. | -| `pipelines.tags.` | ✅ | The tag name/wildcard to apply specific Bitbucket pipeline step configuration within. | -| `pipelines.tags..parallel` | ✅ | Parallel (concurrent step) configuration for tag builds of a Bitbucket pipeline. View the available parallel [properties](#parallel-pipelinestypeparallel) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel). | -| `pipelines.tags..step` | ✅ | Individual step configuration for tag builds within a Bitbucket pipeline. View the available step [properties](#step-pipelinestypestep) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#The-Step-property). | -| `pipelines.tags..stage` | ✅ | Stage configuration for tag builds of a Bitbucket pipelines. View the available stage [properties](#stage-pipelinestypestage) supported by the Migrations Tool - and additional property information in the Bitbucket Pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage). | - -## Pipeline Properties (`pipelines..`) - -> [!NOTE] -> Each starting pipeline condition listed [above](#pipeline-starting-conditions-pipelinesstart-condition) can support various pipeline properties: -> - `parallel`: The grouping of multiple steps within a Bitbucket pipeline to run concurrently. -> - `step`: A logical execution unit that makes up a specific workflow within a Bitbucket pipeline. -> - `stage`: The grouping of multiple Bitbucket pipeline steps with shared properties. -> - `variables`: Customized variable definition to utilise within a custom Bitbucket pipeline starting condition. -> -> For information on each of these individual properties, refer to the reference within the Bitbucket Pipelines documentation for [parallel](https://support.atlassian.com/bitbucket-cloud/docs/parallel-step-options/#Parallel), [step](https://support.atlassian.com/bitbucket-cloud/docs/step-options/#The-Step-property), [stage](https://support.atlassian.com/bitbucket-cloud/docs/stage-options/#Stage) and [variable](https://support.atlassian.com/bitbucket-cloud/docs/pipeline-start-conditions/#Custom--manual--pipeline-variables) properties. -> -> Additionally, implementation of these pipeline properties can be enhanced with best practices through the use of [Dynamic Pipelines](https://buildkite.com/docs/pipelines/defining-steps#dynamic-pipelines) to generate and upload pipeline configuration dynamically, using [conditionals](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-pipelines) at both pipelines/step level to apply jobs only on certain conditions and setting [trigger steps](https://buildkite.com/docs/pipelines/trigger-step) with required attributes/environment variable configuration passed through to triggered builds. - -### Parallel (`pipelines..parallel`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines..parallel` | ✅ | The grouping of multiple steps within a Bitbucket pipeline that are to be run concurrently. By default, Buildkite executes steps in parallel unless [implicit or explicit dependencies](https://buildkite.com/docs/pipelines/dependencies) are set. Parallel Bitbucket pipeline steps are transitioned into a [group step](https://buildkite.com/docs/pipelines/group-step) within the generated Buildkite pipeline without explicit dependencies. | -| `pipelines..parallel.fail-fast` | ❌ | Whether a Bitbucket pipeline allows this parallel step to fail entirely if it fails (set as `true`), or allows failures (set as `false`). Consider using a combination of `soft_fail` and/or `cancel_on_build_failing` in the corresponding Buildkite command steps' [attributes](https://buildkite.com/docs/pipelines/command-step#command-step-attributes) for a similar [approach](https://buildkite.com/docs/pipelines/command-step#fail-fast). | - -### Step (`pipelines..step`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines..step.after-script` | ❌ | The actions that a Bitbucket pipeline will undertake after the commands in the `script` key are run. For similar behaviour, a [repository-level](https://buildkite.com/docs/agent/v3/hooks#hook-locations-repository-hooks) `pre-exit` hook approach will yield similar behaviour - running at the latter end of the [job lifecycle](https://buildkite.com/docs/agent/v3/hooks#job-lifecycle-hooks). | -| `pipelines..step.artifacts` | ⚠️ | Build artifacts that will be required for steps later in the Bitbucket pipeline (by default, not obtained unless an explicit `buildkite-agent artifact download` [command](https://buildkite.com/docs/agent/v3/cli-artifact#downloading-artifacts) is run beforehand within the generated Buildkite command step). Artifacts that are specified (whether one specific file, or multiple) will be set within the generated command step within the `artifact_paths` [key](https://buildkite.com/docs/pipelines/command-step). Each file found matching (or via glob syntax) will be uploaded to Buildkite's [Artifact storage](https://buildkite.com/docs/agent/v3/cli-artifact) that can be obtained in later steps. | -| `pipelines..step.caches` | ✅ | Step-level dependencies downloaded from external sources (Docker, Maven, PyPi for example) which will be able to be re-used in later Bitbucket pipeline steps. Caches that are set at step level (or through the top-level `definition.cache.` property) are translated in the corresponding Buildkite pipeline utilising the [cache-buildkite-plugin](https://github.com/buildkite-plugins/cache-buildkite-plugin) to store the downloaded dependencies for re-use between Buildkite builds. | -| `pipelines..step.condition` | ⚠️ | The configuration to prevent a Bitbucket pipeline step from running unless the specific conditional is met. Translated to an inline conditional (`if`) within the corresponding Buildkite pipelines' command step's `commands` - based on a `git diff` of the base branch. | -| `pipelines..step.condition.changeset.includePaths` | ⚠️ | The specific file (or files) that need to be detected as changed for the `condition` to apply based. This can be set as specific files - or wildcards that match multiple files in a specific directory/directories.

Translated to a script that will review the changed files through git. This means that the step itself will actually run and just be marked as passed, which may not be what you want or need.

You may want to consider utilising the [monorepo-diff-buildkite-plugin](https://github.com/buildkite-plugins/monorepo-diff-buildkite-plugin); watching for specific folders/files and uploading resultant [Dynamic pipelines](https://buildkite.com/docs/pipelines/defining-steps#dynamic-pipelines) upon diff detection. | -| `pipelines..step.clone` | ⚠️ | Clone options for a specific step of a Bitbucket pipeline. The majority of these options should be set on a Buildkite agent itself via [configuration](https://buildkite.com/docs/agent/v3/configuration) of properties such as the clone flags (`git-clone-flags`, `git-clone-mirror-flags` if utilising a Git mirror), fetch flags (`git-fetch-flags`) - or changing the entire checkout process in a customised [plugin](https://buildkite.com/docs/plugins/writing) overriding the default agent `checkout` hook. Sparse checkout options are supported (with the `sparse-checkout` sub-property) | -| `pipelines..step.deployment` | ❌ | The environment set for the Bitbucket Deployments dashboard. This has no translatable equivalent within Buildkite. | -| `pipelines..step.docker` | ❌ | The availability of docker in a specific Bitbucket pipeline step. This will depend on the agent configuration that the corresponding Buildkite command step is being targeted to run said job has available. Consider [tagging](https://buildkite.com/docs/agent/v3/cli-start#tags) agents with `docker=true` to ensure Buildkite command steps requiring hosts with Docker installed and configured to accept/run specific jobs. | -| `pipelines..step.fail-fast` | ❌ | Whether a specific step of a Bitbucket pipeline allows a parallel step to fail entirely if it fails (set as `true`), or allows failures (set as `false`). Consider using a combination of `soft_fail` and/or `cancel_on_build_failing` in the corresponding Buildkite command steps' [attributes](https://buildkite.com/docs/pipelines/command-step#command-step-attributes) for a similar [approach](https://buildkite.com/docs/pipelines/command-step#fail-fast). | -| `pipelines..step.image` | ✅ | The container image that is to be applied for a specific step within a Bitbucket pipeline. Images set at this level will be applied irrespective of the pipeline-level `image` key that is set, and will be applied in the corresponding Buildkite pipeline using the [docker-buildkite-plugin](https://github.com/buildkite-plugins/docker-buildkite-plugin).

The `aws`, `aws.oidc`, `name`, `username` and `password` sub-properties are supported through the use of the corresponding plugin ([Docker Login](https://github.com/buildkite-plugins/docker-login-buildkite-plugin/) or [ECR](https://github.com/buildkite-plugins/ecr-buildkite-plugin/)). | -| `pipelines..step.max-time` | ✅ | The maximum allowable time that a step within a Bitbucket pipeline is able to run for. Translates to the corresponding Buildkite pipelines' command step `timeout_in_minutes` attribute. | -| `pipelines..step.name` | ✅ | The name of a specific step within a Bitbucket pipeline. Translates to a Buildkite command step's `label`. | -| `pipelines..step.oidc` | ✅ | Open ID Connect configuration that will be applied for this Bitbucket pipeline step. The generated command step in the corresponding Buildkite pipeline will [request](https://buildkite.com/docs/agent/v3/cli-oidc#request-oidc-token) an OIDC token and export it into the job environment as `BITBUCKET_STEP_OIDC_TOKEN` (to be passed to `sts` to assume an AWS role for example) | -| `pipelines..step.runs-on` | ✅ | Allocating the Bitbucket pipeline to run on a self-hosted runner with the specific label. All `runs-on` values will be set as agent [tags](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) in the Buildkite command step for targeting on specific Buildkite agents within an organization. | -| `pipelines..step.services` | ⚠️ | The name of one or more services defined at `definitions.services.` that will be applied for this step. Translated to utilise the service configuration with the [docker-compose-buildkite-plugin](https://github.com/buildkite-plugins/docker-compose-buildkite-plugin).

Generated configuration will need to be saved to a `compose.yaml` file within the repository, and the image utilised with the Buildkite command step as `app`.

Refer to the Bitbucket pipelines [documentation](https://support.atlassian.com/bitbucket-cloud/docs/databases-and-service-containers/) for more details on service containers and configuration references.

Authentication based parameters will not be translated to the corresponding Buildkite pipeline if defined. | -| `pipelines..step.script` | ✅ | The individual commands that make up a specific step. Each is translated into a singular command within the `commands` key of a Buildkite command step. | -| `pipelines..step.script.pipe` | ❌ | Re-usable modules to make configuration in Bitbucket pipelines easier and modular. Consider exploring the suite of available [Buildkite Plugins](https://buildkite.com/plugins) for corresponding functionality that is required. | -| `pipelines..step.size` | ✅ | Allocation of sizing options for the given memory for a specific step within a Bitbucket pipeline. The `size` value will be set as an agent [tag](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) in the Buildkite command step for targeting on specific Buildkite agents within an organization. | -| `pipelines..step.trigger` | ✅ | The configuration setting the running of a Bitbucket pipeline step manually or automatically (latter being defaulted). For `manual` triggers - an [input step](https://buildkite.com/docs/pipelines/input-step) is inserted into the generated Buildkite pipeline before the specified `script` within a further command step. Explicit dependencies with `depends_on` are set between the two steps; requiring manual processing. | - -### Stage (`pipelines..stage`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines..stage` | ✅ | The logical grouping of one or more Bitbucket pipeline steps. Bitbucket pipeline stages are translated into the corresponding Buildkite pipeline as a [group step](https://buildkite.com/docs/pipelines/group-step). | -| `pipelines..stage.condition.changeset.includePaths` | ⚠️ | The specific file (or files) that need to be detected as changed for the `condition` to apply based. This can be set as specific files - or wildcards that match multiple files in a specific directory/directories.

Translated to a script that will review the changed files through git. This means that the step itself will actually run and just be marked as passed, which may not be what you want or need.

You may want to consider utilising the [monorepo-diff-buildkite-plugin](https://github.com/buildkite-plugins/monorepo-diff-buildkite-plugin); watching for specific folders/files and uploading resultant [Dynamic pipelines](https://buildkite.com/docs/pipelines/defining-steps#dynamic-pipelines) upon diff detection. | -| `pipelines..stage.name` | ✅ | The name of the Bitbucket pipeline stage. Transitioned to the `group` label of the corresponding Buildkite [group step](https://buildkite.com/docs/pipelines/group-step). | -| `pipelines..stage.steps` | ✅ | Individual step configuration for a Bitbucket pipeline stage. See configuration options in this section (`pipelines.default.step.`) for supported/unsupported properties. | -| `pipelines..stage.trigger` | ✅ | The configuration setting the running of a Bitbucket pipeline stage manually or automatically (latter being defaulted). For `manual` triggers - an [input step](https://buildkite.com/docs/pipelines/input-step) is inserted into the generated Buildkite pipeline's group step before the specified `steps` of this stage. An explicit dependencies with `depends_on` are set between the input step and the following steps to ensure manual processing is required for these to run. | - -### Variables (`pipelines..variables`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `pipelines..variables` | ⚠️ | Custom variables that are passed to Bitbucket pipeline steps. Each variable defined in a Bitbucket pipeline step is translated to a Buildkite [input step](https://buildkite.com/docs/pipelines/input-step) with/without defaults and allowed values specified below.

Variables that are translated into the corresponding [input step](https://buildkite.com/docs/pipelines/input-step) within the generated Buildkite pipeline will require to be fetched in subsequent steps through a `buildkite-agent meta-data get` [command](https://buildkite.com/docs/agent/v3/cli-meta-data#getting-data). | -| `pipelines..variables.name` | ✅ | The variables' name: translated to the `key` attribute of a specific `field` of an [input step](https://buildkite.com/docs/pipelines/input-step) (text entry).| -| `pipelines..variables.default` | ✅ | The default variable value if no value is set. Set as the `default` attribute within the `field` of an [input step](https://buildkite.com/docs/pipelines/input-step). | -| `pipelines..variables.description` | ✅ | The description of the variable. Translated to the `text` attribute of a specific `field` within the generated [input step](https://buildkite.com/docs/pipelines/input-step). | -| `pipelines..variables.allowed-values` | ✅ | The variable's allowed values: each option is translated to a singular `options` object with given value of a specific `field` of an [input step](https://buildkite.com/docs/pipelines/input-step). | - diff --git a/docs/CircleCI.md b/docs/CircleCI.md deleted file mode 100644 index d07e65c1..00000000 --- a/docs/CircleCI.md +++ /dev/null @@ -1,94 +0,0 @@ -# CircleCI - -The Buildkite Migration tool's currently supported (✅), partially supported (⚠️) and unsupported (❌) properties in translation of CircleCI pipelines to Buildkite pipelines are listed below. - -### Logical Operators/Helper Keys - -> [!NOTE] -> The Buildkite Migration tool supports the use of YAML aliases - re-usable snippets of configuration to apply to a specific point in a CircleCI pipeline. These are defined with a `&` (anchor) within the top-level `aliases` key and substituted into CircleCI pipeline configuration with `*`: for example, `*tests`. Configuration defined by an alias will be respected and parsed accordingly at the specified section of the pipeline. - -| Key | Supported? | Notes | -| --- | --- | --- | -| `and` | ⚠️ | Logical operator for denoting all inputs required to be true. Supported with the utilisation of the `when` key within setting up conditional `workflow` runs. | -| `or` | ⚠️ | Logical operator for describing if any of the inputs are true. Supported with the utilisation of the `when` key within setting up conditional `workflow` runs. | -| `not` | ⚠️ | Logical operator for negating input. Supported with the utilisation of the `when` key within setting up conditional `workflow` runs. | - -### Commands (`commands`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `commands` | ✅ | A `command` defined in a CircleCI pipeline is a reusable set of instructions with parameters that can be inserted into required `job` executions. Commands can have their own set list of `steps` that are translated through to the generated [command step](https://buildkite.com/docs/pipelines/command-step)'s `commands`. If a `command` contains a `parameters` key, they are respected when used in jobs/workflows and their defaults values used when not specified. | - -### Executors (`executors`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `executors` | ✅ | The `executor` key defined at topmost-level in a CircleCI workflow maps to the use of the `executor` key specificed within a specific `job`. Supported execition environments include `machine`, `docker`, `macos` and `windows`; further information can be found in the Jobs table below. The execution environment in Buildkite is specified with each environment's applied [tags](https://buildkite.com/docs/agent/v3/cli-start#setting-tags) in their generated [command step](https://buildkite.com/docs/tutorials/parallel-builds#parallel-jobs), for which can be [targeted](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) when creating builds. | - -### Jobs (`jobs`) - -#### General - -| Key | Supported? | Notes | -| --- | --- | --- | -| `jobs` | ✅ | A collection of steps that are run on a single worker unit: whether that is on a host directly, or on a virtualised host (such as within a Docker container). Orchestrated with `workflows`. | -| `jobs.` | ✅ | The named, induvidual `jobs` that makes up part of a given `workflow`. | -| `jobs..environment` | ✅ | The `job` level environment variables of a CircleCI pipeline. Applied in the generated [command step](https://buildkite.com/docs/pipelines/command-step) as [step level](https://buildkite.com/docs/pipelines/environment-variables#runtime-variable-interpolation) environment variables with the `env` key. | -| `jobs..parallelism` | ❌ | A `parallelism` parameter (if defined greater than 1) will create a seperate execution environment and will run the `steps` of the specific `job` in parallel. In Buildkite - a similar `parallelism` key can be set to a [command step](https://buildkite.com/docs/tutorials/parallel-builds#parallel-jobs) which will run the defined `command` over seperate jobs (sharing the same agent [queues](https://buildkite.com/docs/agent/v3/queues#setting-an-agents-queue)/[tags](https://buildkite.com/docs/agent/v3/cli-start#setting-tags) targets). | -| `jobs..parameters` | ✅ | Reusable keys that are used within `step` definitions within a `job`. Default parameters that are specified in a `parameters` block are passed through into the [command step](https://buildkite.com/docs/pipelines/command-step)'s `commands` if specified. | -| `jobs..shell` | ❌ | The `shell` property sets the default shell that is used across all commands within all steps. This should be configured on the agent - or by defining the `shell` [option](https://buildkite.com/docs/agent/v3/cli-start#shell) when starting a Buildkite agent: which will set the shell command used to interpret all build commands. | -| `jobs..steps` | ✅ | A collection of non-`orb` `jobs` commands that are executed as part of a CircleCI `job`. Steps can be defined within an `alias`. All `steps` within a singular `job` are translated to the `commands` of a shared [command step](https://buildkite.com/docs/pipelines/command-step) within the generated Buildkite pipeline to ensure they share the same execution environment. | -| `jobs..working_directory` | ✅ | The location of the executor where steps are run in. If set, a change directory (`cd`) command is created within the shared `commands` of a Buildkite [command step](https://buildkite.com/docs/pipelines/command-step) to the desired location. | - -#### Executors - -> [!NOTE] -> While the Buildkite Migration Tool will translate the below executor types listed; the prerequisite of using the generated steps will require the relevant OS, dependencies and tooling (for example, Docker, XCode etc) on targeted agents. Buildkite offers the [Elastic CI Stack for AWS](https://github.com/buildkite/elastic-ci-stack-for-aws?tab=readme-ov-file#supported-features) as a fully scalable Buildkite agent fleet on AWS with a suite of tooling installed by default. Additionally, customised agents can be [setup](https://buildkite.com/docs/agent/v3/configuration) to target builds that require specific OSes/tooling. - -| Key | Supported? | Notes | -| --- | --- | --- | -| `jobs..docker` | ✅ | Specifies that the `job` will run within a Docker container (by its `image` property) with the use of the [Docker Buildkite Plugin](https://github.com/buildkite-plugins/docker-buildkite-plugin) or [Docker Compose Buildkite Plugin](https://github.com/buildkite-plugins/docker-compose-buildkite-plugin). Additionally, the [Docker Login Plugin](https://github.com/buildkite-plugins/docker-login-buildkite-plugin) is appended if an `auth` property is defined, or the [ECR Buildkite Plugin](https://github.com/buildkite-plugins/ecr-buildkite-plugin) if an `aws-auth` property is defined within the `docker` property. Sets the [agent targeting](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) for the generated [command step](https://buildkite.com/docs/pipelines/command-step) to `executor_type: docker`. | -| `jobs..executor` | ✅ | Specifies the execution environment based from an executor definition supplied in the top-level `executors` key. | -| `jobs..macos` | ✅ | Specifies that the `job` will run on a macOS bases execution environment. The [agent targeting](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) tags for the generated [command step](https://buildkite.com/docs/pipelines/command-step) will be set to `executor_type: osx`, as well as the specified version of `xcode` from the `macos` parameters as `executor_xcode: `. | -| `jobs..machine` | ✅ | Specifies that the `job` will run on a machine execution environment. This translates to [agent targeting](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) for the generated [command step](https://buildkite.com/docs/pipelines/command-step) through the tags of `executor_type: machine` and `executor_image: self-hosted`. | -| `jobs..resource_class` | ✅ | The specification of compute that the executor will require in running a job. This is used to specify the `resource_class` [agent targeting](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) tag for the corresponding [command step](https://buildkite.com/docs/pipelines/command-step). | -| `jobs..windows` | ✅ | Specifies that the `job` will run on a Windows based execution environment. The [agent targeting](https://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents) tags for the generated [command step](https://buildkite.com/docs/pipelines/command-step) will be set to `executor_type: windows`. | - -### Orbs (`orbs`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `orbs` | ❌ | Orbs are currently not supported by the Buildkite Migration tool, and should be translated by hand if required to utilise within a Buildkite pipeline. The Buildkite platform has reusable [plugins](https://buildkite.com/docs/plugins/directory) that provide a similar experience for integrating various common (and third party integration) tasks throughout a Buildkite pipeline, such as [logging into ECR](https://github.com/buildkite-plugins/ecr-buildkite-plugin), running a step within a [Docker container](https://github.com/buildkite-plugins/docker-buildkite-plugin), running multiple Docker images through a [compose file](https://github.com/buildkite-plugins/docker-compose-buildkite-plugin), triggering builds in a [monorepo setup](https://github.com/buildkite-plugins/monorepo-diff-buildkite-plugin) and more. | - -### Parameters (`parameters`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `parameters` | ❌ | Pipeline-level parameters that allow for utilisation in the pipeline level configuration. Pipeline level [environment variables](https://buildkite.com/docs/pipelines/environment-variables#defining-your-own) allow for utilising variables in Buildkite pipeline configuration with [conditionals](https://buildkite.com/docs/pipelines/conditionals). | - -### Setup (`setup`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `setup` | ❌ | Allows for the conditional configuration trigger from outside the .circleci directory - not applicable with Buildkite. Buildkite offers [trigger steps](https://buildkite.com/docs/pipelines/trigger-step) that allow for triggering builds from another pipeline. | - -### Version (`version`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `version` | ❌ | The version of the CircleCI pipeline configuration applied to this pipeline. No equivalent mapping exists in Buildkite. Attributes for required and optional attributes in the various step types supported in Buildkite are listed in the [docs](https://buildkite.com/docs/pipelines/step-reference). | - -### Workflows (`workflows`) - -| Key | Supported? | Notes | -| --- | --- | --- | -| `workflows` | ✅ | A a collection of `jobs`, whose ordering defines how a CircleCI pipeline is run. | -| `workflows.` | ✅ | An induvidual named workflow that makes up part of the CircleCI pipeline's definition. If a CircleCI pipeline has more than 1 `workflow` specified, each will be transitioned to a [group step](https://buildkite.com/docs/pipelines/group-step). | -| `workflows..jobs` | ✅ | The induvidually named, non-`orb` `jobs` that make up part of this specific workflow.

Customised `jobs` defined as part of a `workflow` will be translated to a Buildkite [command step](https://buildkite.com/docs/pipelines/command-step) within the generated pipeline, and `jobs` with the `approval` type will be translated to a Buildkite [block step](https://buildkite.com/docs/pipelines/block-step). | -| `workflows..jobs..branches` | ❌ | The `branches` that will be allowed/blocked for a singular `job`. Presently, the Buildkite Migration tool supports setting `filters` within `workflows`: and in particular, `branches` and `tags` sub-properties in setting a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps) in the generated pipeline. | -| `workflows..jobs..filters` | ✅ | The `branches` and `tag` filters that will determine the eligibility for a CircleCI to run. | -| `workflows..jobs..filters.branches`| ✅ | The specific `branches` that are applicable to the `job`'s filter. Translated to a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps). | -| `workflows..jobs..filters.tags` | ✅ | The specific `tags` that are applicable to the `job`'s filter. Translated to a [step conditional](https://buildkite.com/docs/pipelines/conditionals#conditionals-in-steps). | -| `workflows..jobs..matrix` | ✅ | The `matrix` key allows running a specific job as part of a workload with different values. Translated to a [build matrix](https://buildkite.com/docs/pipelines/build-matrix) setup within a [command step](https://buildkite.com/docs/pipelines/command-step). | -| `workflows..jobs..requires` | ✅ | A list of `jobs` that require this `job` to start. Translated to explicit [step dependencies](https://buildkite.com/docs/pipelines/dependencies#defining-explicit-dependencies) with the `depends_on` key. | -| `workflows..when` | ✅ | Conditionals that allow for running a workflow under certain conditions. The Buildkite Migration tool allows for the speicification using Logical operators `and`, `or` and `not` in creating command conditionals. | \ No newline at end of file diff --git a/docs/GHA.md b/docs/GHA.md deleted file mode 100644 index 0b6ca061..00000000 --- a/docs/GHA.md +++ /dev/null @@ -1,66 +0,0 @@ -# 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](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions) stored within GitHub organizations or repositories (such as `{{ secrets.FOO }}`).

A core principle of the Buildkite's [architecture](https://buildkite.com/docs/pipelines/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](https://buildkite.com/docs/pipelines/secrets#using-a-secrets-storage-service) such as [HashiCorp Vault](https://aws.amazon.com/secrets-manager/) or [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/), accompanied by the use of their respective [plugin](https://github.com/buildkite-plugins) can be configured to read and utilize secrets within Buildkite pipelines. Additionally, the [S3 Secrets Buildkite plugin](https://github.com/buildkite/elastic-ci-stack-s3-secrets-hooks) can be installed within a Buildkite agent - this service automatically included within [Elastic CI Stack for AWS](https://github.com/buildkite/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](https://buildkite.com/docs/pipelines/controlling-concurrency#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..concurrency`](#jobs-jobs). | - -## Defaults (`defaults`) - -| Key | Supported? | Notes | -| --- | ---------- | ----- | -| `defaults.run` | ❌ | Buildkite pipeline definitions allow for common pipeline configuration to be applied with [YAML anchors](https://buildkite.com/docs/plugins/using#using-yaml-anchors-with-plugins), as well as setting up customised [agent](https://buildkite.com/docs/agent/v3/hooks#agent-lifecycle-hooks) and [job](https://buildkite.com/docs/agent/v3/hooks#job-lifecycle-hooks) 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](https://buildkite.com/docs/pipelines/environment-variables#environment-variable-precedence) 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](https://buildkite.com/docs/pipelines/defining-steps#job-states) that will be distributed and assigned to the matching agents meeting its specific queue and/or tag [targeting](h.ttps://buildkite.com/docs/pipelines/defining-steps#targeting-specific-agents). Each job is run within its own separate environment, with potentially different environment variables (for example those defined at [step](https://buildkite.com/docs/pipelines/command-step#command-step-attributes) level) - and is not always guaranteed to run on the same agent depending on targeting rules specified/agent fleet setup. - -| Key | Supported? | Notes | -| --- | ---------- | ----- | -| `jobs..concurrency` | ⚠️ | The `group` name inside a `concurrency` definition inside a job maps to the `concurrency_group` [key](https://buildkite.com/docs/pipelines/controlling-concurrency#concurrency-groups) available within Buildkite.

The `cancel-in-progress` optional value maps to the Buildkite pipeline setting of [Cancel Intermediate Builds](https://buildkite.com/docs/pipelines/skipping#cancel-running-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..env` | ✅ | Environment variables defined within the context of each of a workflow's `jobs` are transitioned to [step level](https://buildkite.com/docs/pipelines/environment-variables#runtime-variable-interpolation) environment variables. | -| `jobs..runs-on` | ✅ | This attribute is mapped to the agent targeting [tag](https://buildkite.com/docs/agent/v3/queues#targeting-a-queue) `runs-on`. Jobs that target custom `tag` names will have a `queue` target of `default`. | -| `jobs..steps`| ✅ | Steps that make up a particular action's `job`. | -| `jobs..steps.env` | ✅ | Environment variables that are defined at `step` level are translated as a variable definition within the `commands` of a Buildkite [command step](https://buildkite.com/docs/pipelines/command-step). | -| `jobs..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..steps.strategy` | ✅ | Allows for the conversion of a step's `strategy` (matrix) to create multiple jobs of a combination of values. | -| `jobs..steps.strategy.matrix` | ✅ | A `matrix` key inside of a step's `strategy` will be translated to a [Buildkite build matrix](https://buildkite.com/docs/pipelines/build-matrix). | -| `jobs..steps.strategy.matrix.include` | ✅ | Key/value pairs to add in the generated [matrix](https://buildkite.com/docs/pipelines/build-matrix)'s combinations. | -| `jobs..steps.strategy.matrix.exclude`| ✅ | Key/value pairs to exclude in the generated [matrix](https://buildkite.com/docs/pipelines/build-matrix)'s combinations (`skip`). | -| `jobs..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](https://buildkite.com/docs/apis/rest-api/pipelines#update-a-pipeline) or [GraphQL](https://buildkite.com/docs/apis/graphql/schemas/input-object/pipelineupdateinput) 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](https://buildkite.com/docs/pipelines/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](https://buildkite.com/docs/apis/managing-api-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](https://buildkite.com/docs/apis/managing-api-tokens#token-scopes) that applies to interactions with the [REST](https://buildkite.com/docs/apis/rest-api) API, and can be configured with permission to interact with Buildkite's [GraphQL](https://buildkite.com/docs/apis/graphql-api) 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](https://buildkite.com/docs/integrations/github#connect-your-buildkite-account-to-github-using-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](https://buildkite.com/docs/apis/rest-api/builds#create-a-build) and [GraphQL](https://buildkite.com/docs/apis/graphql/schemas/mutation/buildcreate) APIs. |