merge queue: embarking main (b20a893) and #10813 together

src/content/docs/ci-insights/test-frameworks/rspec.mdx

@@ -1,41 +1,31 @@
 ---
 title: RSpec Integration with CI Insights
-description: Report your test results from RSpec tests to CI Insights
+description: Report your test results from RSpec to CI Insights
 ---
 
 import rspecLogo from "../../../images/ci-insights/rspec/logo.svg"
-import CommonTroubleshootingTips from "./_common-troubleshooting-tips.mdx"
-import GhaMergifyCiQuarantineSetup from "./_gha_mergify_ci_quarantine_setup.mdx"
 import IntegrationLogo from "../../../../components/IntegrationLogo.astro"
-import MergifyCIUploadStep from "../../../../components/MergifyCIUploadStep.astro"
 import CIInsightsSetupNote from "../../../../components/CIInsightsSetupNote.astro"
-import MergifyCIUploadStepMatrix from "../../../../components/MergifyCIUploadStepMatrix.astro"
 
 <IntegrationLogo src={rspecLogo} alt="RSpec logo" />
 
-This guide shows how to generate JUnit reports from your RSpec tests and upload
-them to **CI Insights** using a GitHub Actions workflow.
+This guide explains how to integrate RSpec with CI Insights using the
+`rspec-mergify` gem. Once installed, test results are automatically uploaded to
+CI Insights without any extra workflow changes.
 
-## Generate a JUnit Report with RSpec
+## Installation
 
-RSpec supports JUnit XML output through the built-in JUnit formatter. You can
-configure RSpec to output JUnit reports using command-line options or
-configuration files.
+You need to install the
+[`rspec-mergify`](https://rubygems.org/gems/rspec-mergify) gem to automatically
+upload your test results to **CI Insights**.
 
-### Using Command Line Options
+### Gemfile
 
-```bash
-bundle exec rspec --format RspecJunitFormatter --out junit.xml
-```
-
-### Installing the JUnit Formatter
-
-First, add the JUnit formatter gem to your Gemfile:
+Add the gem to your `Gemfile`:
 
 ```ruby
-# Gemfile
 group :test do
-  gem 'rspec-junit-formatter'
+  gem 'rspec-mergify'
 end
 ```
 
@@ -45,87 +35,58 @@ Then run:
 bundle install
 ```
 
-### Using RSpec Configuration
+### Gem Install
 
-Add the formatter to your `.rspec` file:
-
-```text
---format RspecJunitFormatter
---out junit.xml
-```
-
-Or configure it in your `spec_helper.rb`:
-
-```ruby
-# spec/spec_helper.rb
-RSpec.configure do |config|
-  config.add_formatter('RspecJunitFormatter', 'junit.xml')
-end
-```
-
-### Using Multiple Formatters
-
-You can use multiple formatters simultaneously:
+Alternatively, install it directly:
 
 ```bash
-bundle exec rspec --format documentation --format RspecJunitFormatter --out junit.xml
+gem install rspec-mergify
 ```
 
-### Using Rake Task
-
-You can also create a Rake task in your `Rakefile`:
-
-```ruby
-require 'rspec/core/rake_task'
-
-RSpec::Core::RakeTask.new(:spec_junit) do |t|
-  t.rspec_opts = '--format RspecJunitFormatter --out junit.xml'
-end
-```
-
-Then run:
-
-```bash
-bundle exec rake spec_junit
-```
-
-## Update Your GitHub Actions Workflow
+## Modify Your Workflow
 
 <CIInsightsSetupNote />
 
-After generating the JUnit report, add a step to upload the results to CI
-Insights using the mergifyio/gha-mergify-ci action.
-
-For example, in your workflow file:
+Your workflow should run your tests as usual while exporting the secret
+`MERGIFY_TOKEN` as an environment variable. You'll need to add the following
+code to the GitHub Actions step running your tests:
 
 ```yaml
-- name: Run RSpec Tests and Generate JUnit Report
-  continue-on-error: true
-  run: bundle exec rspec --format RspecJunitFormatter --out junit.xml
+env:
+  MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
 ```
 
-<MergifyCIUploadStep reportPath="junit.xml" />
-<MergifyCIUploadStepMatrix reportPath="junit.xml" />
+For example:
 
-<GhaMergifyCiQuarantineSetup />
-
-## Verify and Review in CI Insights
+```yaml
+- name: Run RSpec Tests 🧪
+  env:
+    MERGIFY_TOKEN: ${{ secrets.MERGIFY_TOKEN }}
+  run: bundle exec rspec
+```
 
-After pushing these changes:
+The gem automatically collects your test results and sends them to CI Insights.
 
-1. Your GitHub Actions workflow will execute your RSpec tests.
-2. A JUnit report (junit.xml) is generated.
-3. The Mergify CI action uploads the report to CI Insights.
+Check the CI Insights dashboard afterward to view execution metrics, detect
+flaky tests, and gather actionable feedback.
 
-You can then review your test results, including any failures or flaky tests,
-directly in the [CI Insights
-dashboard](https://dashboard.mergify.com/ci-insights/jobs).
+## Environment Variables
 
-## Troubleshooting Tips
+| 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 |
 
-<ul>
-  <li>Gem Installation: Ensure the `rspec-junit-formatter` gem is properly installed and included in your Gemfile.</li>
-  <li>RSpec Configuration: Verify that the formatter is correctly configured in your RSpec setup.</li>
+:::tip
+The gem auto-activates in CI environments (detected via the `CI` environment
+variable). To enable it outside CI, set `RSPEC_MERGIFY_ENABLE=true`.
+:::
 
-  <CommonTroubleshootingTips />
-</ul>
+:::tip
+Use `MERGIFY_TEST_JOB_NAME` to make reports clearer in CI Insights, especially
+when running multiple test suites or using a matrix strategy.
+:::