Triggering pipelines using GitHub Actions

GitHub Actions is a GitHub-based workflow automation platform. You can use the GitHub actions Trigger Buildkite Pipeline to trigger a build on a Buildkite pipeline.

The Trigger Buildkite Pipeline GitHub Action allows you to:

  • Create builds in Buildkite pipelines and set commit, branch, message.
  • Save the build JSON response to ${HOME}/${GITHUB_ACTION}.json for downstream actions.

Find the Trigger Buildkite Pipeline on GitHub Marketplace or follow this link directly.

Trigger Buildkite Pipeline GitHub Action on GitHub

Prerequisites

This tutorial assumes some familiarity with GitHub and using GitHub Actions. You can find the official GitHub Actions documentation here.

Creating the workflow for Buildkite GitHub Actions

  1. If a workflow directory does not exist yet, create the .github/workflows directory in your repo to store the workflow files for Buildkite Pipeline Action.
  2. Create a Buildkite API access token with write_builds scope, and save it to your GitHub repository’s Settings in Secrets. You can read more about Creating encrypted secrets for a repository in GitHub.
  3. Define your GitHub Actions workflow with the details of the pipeline to be triggered. To ensure that the latest version is always used, click "Use latest version" on the Trigger Buildkite Pipeline page. Copy and paste the code snippet provided.
  4. Configure the workflow by setting the applicable configuration options.

Example workflow

The following workflow creates a new Buildkite build on every commit (change my-org/my-deploy-pipeline to the slug of your org and pipeline, and TRIGGER_BK_BUILD_TOKEN to the secrets env var you have defined):

trigger-pipeline-action.yml
on: [push]

steps:
  - name: Trigger a Buildkite Build
    uses: "buildkite/trigger-pipeline-action@v1.6.0"
    env:
      BUILDKITE_API_ACCESS_TOKEN: ${{ secrets.TRIGGER_BK_BUILD_TOKEN }} 
      PIPELINE: "my-org/my-deploy-pipeline"
      BRANCH: "master"
      COMMIT: "HEAD"
      MESSAGE:  "<img class="emoji" title="github" alt=":github:" src="https://buildkiteassets.com/emojis/img-buildkite-64/github.png" draggable="false" /> Triggered from a GitHub Action"

Configuring the workflow

Use the following configuration options:

Env var Description Default
PIPELINE The pipeline to create a build on, in the format <org-slug>/<pipeline-slug>
COMMIT The commit SHA of the build. Optional. $GITHUB_SHA
BRANCH The branch of the build. Optional. $GITHUB_REF
MESSAGE The message for the build. Optional.
BUILD_ENV_VARS Additional environment variables to set on the build, in JSON format. e.g. {"FOO": "bar"}. Optional.
BUILD_META_DATA Meta data to set on the build, in JSON format. e.g. {"FOO": "bar"}. Optional.
IGNORE_PIPELINE_BRANCH_FILTER Ignore pipeline branch filtering when creating a new build. true or false. Optional.

From v1.6.0, optional input parameters can now be used to pass in the configuration options. However, configuration defined as environment variables take precedence over the input parameters.

trigger-pipeline-action.yml
on: [push]

steps:
  - name: Trigger a Buildkite Build
    uses: "buildkite/trigger-pipeline-action@v1.6.0"
    with:
      buildkite-token: ${{ secrets.TRIGGER_BK_BUILD_TOKEN }} 
      pipeline: "my-org/my-deploy-pipeline"
      branch: "master"
      commit: "HEAD"
      message:  "<img class="emoji" title="github" alt=":github:" src="https://buildkiteassets.com/emojis/img-buildkite-64/github.png" draggable="false" /> Triggered from a GitHub Action"
      build-env-vars: '{"TRIGGERED_FROM_GHA": "true"}'
      build-meta-data: '{"FOO": "bar"}'
      ignore-pipeline-branch-filter: true

See Trigger-pipeline-action for more details, code, or to contribute to or raise an issue for the Buildkite GitHub Action.