From e865fddd5a51b316945da038edffc14e3ab10617 Mon Sep 17 00:00:00 2001
From: Remy DUTHU <remy.duthu@gmail.com>
Date: Thu, 25 Jun 2026 16:06:36 +0200
Subject: [PATCH 1/2] docs(ci-insights): Reframe Runners as Self-hosted runners
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Runners product was renamed to Self-hosted runners and split into
Queue, Fleet, and Settings views. The previous page walked through the
screen, which is costly to maintain while this product keeps changing.

Rewrite the page around why the product exists — fleet sizing, spotting
degraded runners, separating wait time from run time, and cost — and
describe the three areas by purpose rather than by what is on screen.
Update the CI Insights overview card and the navigation label to match
the new name.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Change-Id: I24327ea2fd1dbd94929f42bb95e6dbed9abb83fb
---
 src/content/docs/ci-insights.mdx         |   4 +-
 src/content/docs/ci-insights/runners.mdx | 101 ++++++++++++++---------
 src/content/navItems.tsx                 |   2 +-
 3 files changed, 65 insertions(+), 42 deletions(-)

diff --git a/src/content/docs/ci-insights.mdx b/src/content/docs/ci-insights.mdx
index d74639ac08..fa21cfc12d 100644
--- a/src/content/docs/ci-insights.mdx
+++ b/src/content/docs/ci-insights.mdx
@@ -22,11 +22,11 @@ GitHub and covers basic configuration steps.
 
 <DocsetGrid>
   <Docset
-    title="Runners"
+    title="Self-hosted runners"
     path="/ci-insights/runners"
     icon="lucide:server"
   >
-    Track runner fleet performance, queue times, and reliability.
+    Monitor your self-hosted runners' capacity, performance, cost, and reliability.
   </Docset>
   <Docset
     title="Jobs"
diff --git a/src/content/docs/ci-insights/runners.mdx b/src/content/docs/ci-insights/runners.mdx
index 224879ecff..8218d154bb 100644
--- a/src/content/docs/ci-insights/runners.mdx
+++ b/src/content/docs/ci-insights/runners.mdx
@@ -1,57 +1,80 @@
 ---
-title: Runners
-description: Monitor your CI runner fleet's performance, cost, and reliability to detect issues before they impact your pipelines.
+title: Self-hosted runners
+description: Monitor the self-hosted CI runners behind your pipelines so you can spot capacity bottlenecks, degraded machines, and wasted spend.
 ---
 
-The Runners page gives you visibility into your CI runner fleet. Track
-performance, spot bottlenecks, and identify degraded runners before they
-slow down your pipelines.
+Self-hosted runners are the machines that execute your CI. Mergify doesn't provision
+or control them. It watches the jobs they run and turns that data into metrics about
+capacity, performance, cost, and reliability.
 
-Whether you're optimizing costs, investigating slow queue times, or
-monitoring runner health, this page centralizes the metrics you need to
-keep your CI infrastructure running smoothly.
+That fleet is infrastructure you own and pay for, but it usually runs as a black
+box: you only hear about it once builds start queuing or failing. These metrics let
+you base scaling and reliability decisions on what the fleet actually does.
 
 :::note
-  Before using the Runners page, you need to have CI Insights enabled on
-  your repository. See the [CI Insights setup guides](/ci-insights) to
-  get started.
+  Self-hosted runners are part of CI Insights. Enable CI Insights on your repository
+  first. See the [setup guides](/ci-insights) to get started.
 :::
 
-## Configuring Your Fleet
+## Why monitor your runners
 
-Before any runner data appears, you need to configure which runners to
-track. Click **Configure Runner Groups** to set up your fleet.
+The metrics answer a few recurring questions:
 
-**Runner groups** let you organize runners by their group name. You can
-track one or more groups at a time. **Labels** let you optionally filter
-runners further (e.g., by operating system or architecture).
+- **Is the fleet the right size?** Idle runners mean you pay for capacity you don't
+  use. Saturated runners mean jobs wait. Both are expensive, in different ways.
 
-Only runners matching your configuration will appear in the table. You
-can edit this configuration at any time by clicking the **Edit** button
-in the fleet configuration section.
+- **Is a runner degraded?** One slow or flaky machine drags down every job scheduled
+  on it, often without an obvious failure.
 
-:::tip
-  Start with a single runner group to get familiar with the metrics,
-  then expand your configuration as needed.
-:::
+- **Where is CI time going?** Time spent *waiting* for a runner and time spent
+  *running* on it are different problems with different fixes.
+
+- **What is the fleet costing?** Cost per runner and per job shows where spend
+  concentrates.
+
+## What Mergify tracks
+
+Mergify groups these metrics into three areas.
+
+### Queue: is work waiting for a runner?
+
+The queue tracks how long jobs wait to get a runner and how many are waiting,
+grouped by the labels they request. Read the two signals together: rising wait
+times with steady demand point to a capacity problem, so add runners; a spike in
+queued jobs points to a demand surge instead. The aim is to keep runners ahead of
+demand, before queue time starts delaying pull requests.
 
-## Monitoring Your Runners
+### Fleet: how is each runner performing?
 
-Once configured, the runners table gives you an at-a-glance view of each
-runner's performance, queue times, throughput, and health status. Use the
-date range selector to focus on a specific time window.
+The fleet is your runners seen one at a time: throughput, speed, success rate, and
+how each runner compares to its peers. Each runner carries a health status, so an
+underperforming or unstable one is easy to single out. You can also follow each
+runner's trends over time and see how heavily it is being used.
 
-Expanding any runner row reveals detailed metrics including duration
-percentiles (median, p95, p99), queue time breakdowns, total runs, failure
-rate, and cost data.
+### Settings: what does Mergify monitor?
 
-Each runner is assigned a **health status** (Healthy, Unstable, or
-Degraded) that surfaces runners needing attention based on their success
-rate and relative performance compared to their group.
+You decide which runner groups and labels Mergify watches. Because metrics are
+aggregated by runner group, this is also how you scope monitoring to the runners that
+matter.
 
-:::tip
-  High average queue times may indicate your fleet needs scaling. If a
-  runner shows a Degraded status, investigate potential infrastructure
-  issues. Use the "vs Group" comparison to quickly spot outliers
-  underperforming relative to their peers.
+## Key concepts
+
+- **Runner groups and labels.** Runners are organized into groups, and labels (the
+  `runs-on` values a job requests) identify which kind of runner handled the work.
+  Mergify uses the group to scope what it monitors and to compare each runner against
+  its peers.
+
+- **Long-lived runners only.** This page tracks persistent runners. Ephemeral runners
+  that exist for a single job aren't tracked here; use the [Jobs](/ci-insights/jobs)
+  page for those.
+
+- **Wait time vs. run time.** Wait time is how long a job sits before a runner picks
+  it up; run time is how long it executes once started.
+
+- **Health status.** Derived from a runner's success rate and its speed relative to
+  its group, so machines that need attention surface on their own.
+
+:::note
+  GitHub-hosted runners aren't monitored here. They use a new identity on every run,
+  which makes per-runner metrics unreliable.
 :::
diff --git a/src/content/navItems.tsx b/src/content/navItems.tsx
index 9c613809ce..1daf86e4ca 100644
--- a/src/content/navItems.tsx
+++ b/src/content/navItems.tsx
@@ -76,7 +76,6 @@ const navItems: NavItem[] = [
     icon: 'mergify:ci-insights',
     children: [
       { title: 'Overview', path: '/ci-insights', icon: 'lucide:lightbulb' },
-      { title: 'Runners', path: '/ci-insights/runners', icon: 'lucide:server' },
       { title: 'Jobs', path: '/ci-insights/jobs', icon: 'lucide:list-checks' },
       { title: 'Auto-Retry', path: '/ci-insights/auto-retry', icon: 'lucide:rotate-cw' },
       {
@@ -84,6 +83,7 @@ const navItems: NavItem[] = [
         path: '/ci-insights/flaky-test-detection',
         icon: 'lucide:bug',
       },
+      { title: 'Self-hosted runners', path: '/ci-insights/runners', icon: 'lucide:server' },
       {
         title: 'CI Setup',
         icon: 'lucide:settings',

From 7d47c0fde0ae6239208603d7fa7750b9c093cd72 Mon Sep 17 00:00:00 2001
From: Thomas Berdy <thomas.berdy@mergify.com>
Date: Thu, 25 Jun 2026 17:44:17 +0200
Subject: [PATCH 2/2] docs(cli-reference): document the completions command
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CLI added a top-level `completions` command (prints a shell-completion
script). The schemas-sync bot picks it up automatically, but the editorial
gate — `every group has an editorial label and description` — blocks the sync
PR until the new command is given outward-facing copy.

Add the label, one-line value prop, and grid/nav order for `completions` so it
renders its own card and `/cli/completions` page alongside the other commands.
Unblocks the JSON-schema sync PR Mergifyio/docs#11933.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Change-Id: Ibc06a499b39e922b081ca06be44591070edd4186
---
 src/components/CliReference/cli-schema.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/components/CliReference/cli-schema.ts b/src/components/CliReference/cli-schema.ts
index 85bce775d4..04194ad888 100644
--- a/src/components/CliReference/cli-schema.ts
+++ b/src/components/CliReference/cli-schema.ts
@@ -230,6 +230,7 @@ export const GROUP_ORDER: string[] = [
   'freeze',
   'config',
   'self-update',
+  'completions',
 ];
 
 /** Card/page headings — the CLI counterpart of `TAG_LABELS`. */
@@ -241,6 +242,7 @@ export const GROUP_LABELS: Record<string, string> = {
   freeze: 'Scheduled Freezes',
   config: 'Configuration',
   'self-update': 'Maintenance',
+  completions: 'Shell Completions',
 };
 
 /**
@@ -256,6 +258,7 @@ export const GROUP_DESCRIPTIONS: Record<string, string> = {
   freeze: 'Schedule and manage merge freezes for release windows and maintenance.',
   config: 'Validate your Mergify configuration and simulate actions before you merge.',
   'self-update': 'Update the Mergify CLI to the latest release.',
+  completions: 'Generate a shell completion script to tab-complete Mergify CLI commands and flags.',
 };
 
 /**