---
title: RSpec Integration with Mergify
description: Report your test results from RSpec to Mergify
---

<IntegrationLogo src={rspecLogo} alt="RSpec logo" />

This guide explains how to integrate RSpec with Test Insights using the
`rspec-mergify` gem. Once installed, test results are automatically uploaded to
Test Insights without any extra workflow changes.

## Installation

You need to install the
[`rspec-mergify`](https://rubygems.org/gems/rspec-mergify) gem to automatically
upload your test results to **Test Insights**.

### Gemfile

Add the gem to your `Gemfile`:

```ruby
group :test do
  gem 'rspec-mergify'
end
```

Then run:

```bash
bundle install
```

### Gem Install

Alternatively, install it directly:

```bash
gem install rspec-mergify
```

## Update Your CI Workflow

<CIInsightsSetupNote />

Your workflow should run your tests as usual while exporting the secret
`MERGIFY_TOKEN` as an environment variable.

### GitHub Actions

Add the following to the GitHub Actions step running your tests:

```yaml
env:
  MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
```

For example:

```yaml
- name: Run RSpec Tests 🧪
  env:
    MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
  run: bundle exec rspec
```

### Buildkite

Set `MERGIFY_TOKEN` in the environment of the agents running your tests.
The step itself then needs no Mergify-specific configuration:

```yaml
steps:
  - label: "Run RSpec Tests 🧪"
    command: bundle exec rspec
```

<BuildkiteTokenNote plugin={false} />

The gem automatically collects your test results and sends them to Test Insights.

## Quarantine and Crashed Runs

The gem applies [quarantine](/test-insights/quarantine) inside the RSpec run.
When a quarantined example fails, the gem marks it pending with the message
`Test is quarantined from Mergify Test Insights`, so it does not count as a
failure and does not change RSpec's exit code. The exit code of your test step
already accounts for quarantine, so the step needs nothing more:

- Do not add `continue-on-error: true`. The recipes that upload a JUnit report
  with the `mergifyio/gha-mergify-ci` action need it because the action decides
  the job's result after the tests. Here nothing does, so it would let every
  real failure through.

- There is no step `id` to set and no `test_step_outcome` to pass: both belong
  to that action, which this setup does not use.

A crash cannot pass for a green run either. Quarantine only covers failures
inside an example: a spec file that fails to load, a failing `before(:suite)`
or `after(:context)` hook, or RSpec dying mid-run still exits non-zero and fails
the step. The gem uploads results when the run ends, so a process killed
outright before then, such as by the out-of-memory killer, sends nothing to
Test Insights.

If the gem cannot fetch the quarantine list, it quarantines nothing for that
run, and a quarantined example that fails makes the step fail as usual.

## Verify and Review in Test Insights

After pushing these changes, your next CI run reports its RSpec results
automatically.

<ReviewInTestInsights />

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `MERGIFY_TOKEN` | API authentication token | **Required** |
| `MERGIFY_API_URL` | API endpoint location | `https://api.mergify.com` |
| `RSPEC_MERGIFY_ENABLE` | Force-enable outside CI | `false` |
| `RSPEC_MERGIFY_DEBUG` | Print spans to console | `false` |
| `MERGIFY_TRACEPARENT` | W3C distributed trace context | Optional |
| `MERGIFY_TEST_JOB_NAME` | Test job name identifier | Optional |

:::tip
  The gem auto-activates in CI environments (detected via the `CI` environment
  variable). To enable it outside CI, set `RSPEC_MERGIFY_ENABLE=true`.
:::

:::tip
  Use `MERGIFY_TEST_JOB_NAME` to make reports clearer in Test Insights,
  especially when running multiple test suites or using a matrix strategy.
:::