Buildkite

Here, we'll walk through everything needed to integrate Captain with Buildkite:

An Example `.buildkite/pipeline.yaml`

This document refers to snippets from this example. You can come back here to see the snippets in context.

steps:
  - name: ':rspec:'
    command: |
      # download & install captain
      arch=x86_64 # Supported values are x86_64 or aarch64
      os=linux    # Supported values are linux or darwin

      tmp="$$(mktemp -d)/captain" &&
        wget -qO "$$tmp" "https://releases.captain.build/v1/$$os/$$arch/captain" &&
        install "$$tmp" /usr/local/bin &&
        rm "$$tmp" &&
        captain --version

      # run captain
      captain run captain-examples-rspec
    plugins:
      - docker-compose#v4.11.0:
          run: app
          env:
            - BUILDKITE
            - BUILDKITE_BRANCH
            - BUILDKITE_BUILD_CREATOR_EMAIL
            - BUILDKITE_BUILD_ID
            - BUILDKITE_BUILD_URL
            - BUILDKITE_COMMIT
            - BUILDKITE_JOB_ID
            - BUILDKITE_LABEL
            - BUILDKITE_MESSAGE
            - BUILDKITE_ORGANIZATION_SLUG
            - BUILDKITE_REPO
            - BUILDKITE_RETRY_COUNT
            - RWX_ACCESS_TOKEN

Setting `RWX_ACCESS_TOKEN`

We need to make a rwx access token available as an environment variable called RWX_ACCESS_TOKEN in Buildkite. We'll do this by:

First generating an access token,
setting it in Buildkite

Generating an Access Token

Navigate to your Access Tokens settings page
- Log in to RWX
- From the hamburger navigation menu, select "Manage {organization}"
- Click on "Access Tokens" on the menu on the left
Click "Create new"
Enter a description, such as "GitHub Actions"
Click "Create token"
Copy the Access Token (you'll use it in the next section)

Setting the Access Token in Buildkite

Captain needs to have the access token exposed as an environment variable called RWX_ACCESS_TOKEN.

See [buildkite's docs][buildkite-secrets] for guidance on how to do that.

Installing Captain

In our example, captain runs on a linux x86_64 machine.

Here are supported OS, architectures, and their download URLs:

OS	Architecture	URL
`darwin`	`x86_64`	https://releases.captain.build/v1/darwin/x86_64/captain
`darwin`	`aarch64`	https://releases.captain.build/v1/darwin/aarch64/captain
`linux`	`x86_64`	https://releases.captain.build/v1/linux/x86_64/captain
`linux`	`aarch64`	https://releases.captain.build/v1/linux/aarch64/captain

Buildkite requires escaping $ characters in yaml (with \$ or $$). If you extract these inline scripts into a separate file, un-escape the $ characters.

steps:
  - name: ':rspec:'
    command: |
      # download & install captain
      arch=x86_64 # Supported values are x86_64 or aarch64
      os=linux    # Supported values are linux or darwin

      tmp="$$(mktemp -d)/captain" &&
        wget -qO "$$tmp" "https://releases.captain.build/v1/$$os/$$arch/captain" &&
        install "$$tmp" /usr/local/bin &&
        rm "$$tmp" &&
        captain --version

Integrating Captain with your test framework

Captain integrates with many test frameworks. Find instructions for your specific test framework here.

This example integrates with Ruby's RSpec but can be used as a baseline for integrating with a different framework.

# .captain/config.yaml

test-suites:
  captain-examples-rspec:
    command: bundle exec rspec --format json --out tmp/rspec.json --format progress
    results:
      path: tmp/rspec.json
    output:
      reporters:
        junit-xml: tmp/junit.xml

This example uses Docker. If you're not using docker, you won't have to forward your env as we do below.

# .buildkite/pipeline.yaml

steps:
  - name: ':rspec:'
    command: |
      # ...
      captain run captain-examples-rspec
    plugins:
      - docker-compose#v4.11.0:
          run: app
          env:
            - BUILDKITE
            - BUILDKITE_BRANCH
            - BUILDKITE_BUILD_CREATOR_EMAIL
            - BUILDKITE_BUILD_ID
            - BUILDKITE_BUILD_URL
            - BUILDKITE_COMMIT
            - BUILDKITE_JOB_ID
            - BUILDKITE_LABEL
            - BUILDKITE_MESSAGE
            - BUILDKITE_ORGANIZATION_SLUG
            - BUILDKITE_REPO
            - BUILDKITE_RETRY_COUNT
            - RWX_ACCESS_TOKEN

Partitioning

Captain's partitioning feature works with Buildkite's "Parallel Builds".

Start by updating your Captain configuration to enable partitioning as follows:

# .captain/config.yaml

test-suites:
  captain-examples-rspec:
    # existing config...
    partition:
      command: bundle exec rspec --format json --out tmp/rspec.json --format progress {{ testFiles }}
      globs:
        - spec/**/*_spec.rb

When parallelism is enabled captain run will detect which partition it's on using Buildkite's $BUILDKITE_PARALLEL_JOB and $BUILDKITE_PARALLEL_JOB_COUNT environment variables.

# .buildkite/pipeline.yaml

steps:
  - name: ':rspec: with partitioning'
    parallelism: 2
    command: |
      # ... download captain then ...

      captain run captain-examples-rspec

    plugins:
      - docker-compose#v4.11.0:
          run: app
          env:
            - CAPTAIN_SUITE_ID=captain-examples-rspec
            - BUILDKITE
            - BUILDKITE_BRANCH
            - BUILDKITE_BUILD_CREATOR_EMAIL
            - BUILDKITE_BUILD_ID
            - BUILDKITE_BUILD_URL
            - BUILDKITE_COMMIT
            - BUILDKITE_JOB_ID
            - BUILDKITE_LABEL
            - BUILDKITE_MESSAGE
            - BUILDKITE_ORGANIZATION_SLUG
            - BUILDKITE_PARALLEL_JOB
            - BUILDKITE_PARALLEL_JOB_COUNT
            - BUILDKITE_REPO
            - BUILDKITE_RETRY_COUNT
            - RWX_ACCESS_TOKEN

For more examples of captain in Buildkite, see this example repo and its .Buildkite-ci.yml.