GitLab

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

1. Setting the RWX_ACCESS_TOKEN
2. Installing the Captain CLI
3. Integrating Captain with your test framework

An Example .gitlab-ci.yml

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

image: ruby:3.1.2

before_script:
  - ruby -v
  - bundle install --jobs $(nproc)
  # download captain
  - arch=x86_64 # Supported values are x86_64 or aarch64
  - os=linux # Supported values are linux or darwin
  - tmp="$(mktemp -d)/captain"
  - curl -o $tmp -fsSL "https://releases.captain.build/v1/$os/$arch/captain"
  - install $tmp /usr/local/bin
  - rm $tmp
  - captain --version

rspec:
  script:
    - captain run captain-examples-rspec
  artifacts:
    when: always
    paths:
      - tmp/junit.xml
    reports:
      junit: tmp/junit.xml

Setting RWX_ACCESS_TOKEN

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

1. First generating an access token,
2. setting it in GitLab

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 GitLab

Set your access token in GitLab's CI variable settings. For ease of sharing the access token across projects, we recommend setting it at the instance-level if self-hosting GitLab or at the group level if using hosted GitLab. Here's how to set the access token environment variable for a group:

• On your group's page, hover over "Settings" in the menu on the left and click on "CI/CD"
• Click on "Variables" to expand it, and then click on "Add Variable"
• Enter RWX_ACCESS_TOKEN in the "Key" field
• Paste the Access Token into the "Value" field
• Leave "Type" set to "Variable" and "Environment scope" set to "All"
• Ensure that only "Mask variable" is checked ("Protect variable" flag will prevent the CLI from working properly for feature branches. "Expand variable reference" is unnecessary.)

Installing Captain

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

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

before_script:
  # ...
  # download captain
  - arch=x86_64 # Supported values are x86_64 or aarch64
  - os=linux # Supported values are linux or darwin
  - tmp="$(mktemp -d)/captain"
  - curl -o $tmp -fsSL "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

# .gitlab-ci.yml

rspec:
  script:
    - captain run captain-examples-rspec

Partitioning

Captain's partitioning feature works with GitLab's parallel.

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 GitLab's $CI_NODE_INDEX and $CI_NODE_TOTAL environment variables.

# .gitlab-ci.yml

rspec:
  parallel: 2
  script:
    - captain run captain-examples-rspec

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