GitHub Actions

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

An Example Workflow

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

name: 'Captain CI example'
on:
  pull_request:
  push:
    paths-ignore:
      - README.md
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
      - uses: rwx-research/setup-captain@v1
      - run: captain run captain-examples-rspec
        env:
          RWX_ACCESS_TOKEN: ${{ secrets.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 GitHub. We'll do this by:

First generating an access token,
setting it in GitHub

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 GitHub

Set your access token in GitHub's Actions secrets to make it available in your builds:

On your organization settings page in GitHub, under the Security heading, Expand the "Secrets and variables" menu, then click on Actions.
Click on the "New organization secret" button
Enter RWX_ACCESS_TOKEN for the name
Paste the Access Token that you generated for the Value
Set the Repository access appropriately for the repositories you'd like to integrate into Captain or ABQ
Click Add secret

see GitHub's documentation for more information.

Installing Captain

Add a step that uses our setup-captain action to install the Captain CLI.

jobs:
  test:
    # ...
    steps:
      # ...
      - uses: rwx-research/setup-captain@v1

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

# .github/workflows/ci.yml

jobs:
  test:
    # ...
    steps:
      # ...
      - run: captain run captain-examples-rspec
        env:
          RWX_ACCESS_TOKEN: ${{ secrets.RWX_ACCESS_TOKEN }}

Partitioning

Captain's partitioning feature works with GitHub Action's matrix strategy.:

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

And then use the matrix variables to instruct Captain to run individual partitions.

# .github/workflows/ci.yml

jobs:
  test-partitioned:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        partition_index: ['0', '1']
        partition_total: ['2']
    steps:
      - run: |
          captain run captain-examples-rspec \
          --partition-index ${{ matrix.partition_index }} \
          --partition-total ${{ matrix.partition_total }}
        env:
          RWX_ACCESS_TOKEN: ${{ secrets.RWX_ACCESS_TOKEN }}

For more examples of captain in GitHub, see this example repo and its workflow.