|
1 | 1 | --- |
2 | | -title: Runners |
3 | | -description: Monitor your CI runner fleet's performance, cost, and reliability to detect issues before they impact your pipelines. |
| 2 | +title: Self-hosted runners |
| 3 | +description: Monitor the self-hosted CI runners behind your pipelines so you can spot capacity bottlenecks, degraded machines, and wasted spend. |
4 | 4 | --- |
5 | 5 |
|
6 | | -The Runners page gives you visibility into your CI runner fleet. Track |
7 | | -performance, spot bottlenecks, and identify degraded runners before they |
8 | | -slow down your pipelines. |
| 6 | +Self-hosted runners gives you visibility into the machines that execute your CI. |
| 7 | +Mergify doesn't provision or control these runners. It watches the jobs they run |
| 8 | +and turns that data into metrics about capacity, performance, cost, and reliability. |
9 | 9 |
|
10 | | -Whether you're optimizing costs, investigating slow queue times, or |
11 | | -monitoring runner health, this page centralizes the metrics you need to |
12 | | -keep your CI infrastructure running smoothly. |
| 10 | +That fleet is infrastructure you own and pay for, but it usually runs as a black |
| 11 | +box: you only hear about it once builds start queuing or failing. These metrics let |
| 12 | +you base scaling and reliability decisions on what the fleet actually does. |
13 | 13 |
|
14 | 14 | :::note |
15 | | - Before using the Runners page, you need to have CI Insights enabled on |
16 | | - your repository. See the [CI Insights setup guides](/ci-insights) to |
17 | | - get started. |
| 15 | + Self-hosted runners is part of CI Insights. Enable CI Insights on your repository |
| 16 | + first. See the [setup guides](/ci-insights) to get started. |
18 | 17 | ::: |
19 | 18 |
|
20 | | -## Configuring Your Fleet |
| 19 | +## Why monitor your runners |
21 | 20 |
|
22 | | -Before any runner data appears, you need to configure which runners to |
23 | | -track. Click **Configure Runner Groups** to set up your fleet. |
| 21 | +The metrics answer a few recurring questions: |
24 | 22 |
|
25 | | -**Runner groups** let you organize runners by their group name. You can |
26 | | -track one or more groups at a time. **Labels** let you optionally filter |
27 | | -runners further (e.g., by operating system or architecture). |
| 23 | +- **Is the fleet the right size?** Idle runners mean you pay for capacity you don't |
| 24 | + use. Saturated runners mean jobs wait. Both are expensive, in different ways. |
28 | 25 |
|
29 | | -Only runners matching your configuration will appear in the table. You |
30 | | -can edit this configuration at any time by clicking the **Edit** button |
31 | | -in the fleet configuration section. |
| 26 | +- **Is a runner degraded?** One slow or flaky machine drags down every job scheduled |
| 27 | + on it, often without an obvious failure. |
32 | 28 |
|
33 | | -:::tip |
34 | | - Start with a single runner group to get familiar with the metrics, |
35 | | - then expand your configuration as needed. |
36 | | -::: |
| 29 | +- **Where is CI time going?** Time spent *waiting* for a runner and time spent |
| 30 | + *running* on it are different problems with different fixes. |
| 31 | + |
| 32 | +- **What is the fleet costing?** Cost per runner and per job shows where spend |
| 33 | + concentrates. |
| 34 | + |
| 35 | +## What Mergify tracks |
| 36 | + |
| 37 | +Mergify groups these metrics into three areas. |
| 38 | + |
| 39 | +### Queue: is work waiting for a runner? |
| 40 | + |
| 41 | +The queue tracks how long jobs wait to get a runner and how many are waiting, |
| 42 | +grouped by the labels they request. Read the two signals together: rising wait |
| 43 | +times with steady demand point to a capacity problem, so add runners; a spike in |
| 44 | +queued jobs points to a demand surge instead. The aim is to keep runners ahead of |
| 45 | +demand, before queue time starts delaying pull requests. |
37 | 46 |
|
38 | | -## Monitoring Your Runners |
| 47 | +### Fleet: how is each runner performing? |
39 | 48 |
|
40 | | -Once configured, the runners table gives you an at-a-glance view of each |
41 | | -runner's performance, queue times, throughput, and health status. Use the |
42 | | -date range selector to focus on a specific time window. |
| 49 | +The fleet is your runners seen one at a time: throughput, speed, success rate, and |
| 50 | +how each runner compares to its peers. Each runner carries a health status, so an |
| 51 | +underperforming or unstable one is easy to single out. You can also follow each |
| 52 | +runner's trends over time and see how heavily it is being used. |
43 | 53 |
|
44 | | -Expanding any runner row reveals detailed metrics including duration |
45 | | -percentiles (median, p95, p99), queue time breakdowns, total runs, failure |
46 | | -rate, and cost data. |
| 54 | +### Settings: what does Mergify monitor? |
47 | 55 |
|
48 | | -Each runner is assigned a **health status** (Healthy, Unstable, or |
49 | | -Degraded) that surfaces runners needing attention based on their success |
50 | | -rate and relative performance compared to their group. |
| 56 | +You decide which runner groups and labels Mergify watches. Because metrics are |
| 57 | +aggregated by runner group, this is also how you scope monitoring to the runners that |
| 58 | +matter. |
51 | 59 |
|
52 | | -:::tip |
53 | | - High average queue times may indicate your fleet needs scaling. If a |
54 | | - runner shows a Degraded status, investigate potential infrastructure |
55 | | - issues. Use the "vs Group" comparison to quickly spot outliers |
56 | | - underperforming relative to their peers. |
| 60 | +## Key concepts |
| 61 | + |
| 62 | +- **Runner groups and labels.** Runner names are usually unique per run, so Mergify |
| 63 | + aggregates metrics by group. Labels (the `runs-on` values a job requests) identify |
| 64 | + which kind of runner handled the work. |
| 65 | + |
| 66 | +- **Long-lived runners only.** This page tracks persistent runners. Ephemeral runners |
| 67 | + that exist for a single job aren't tracked here; use the [Jobs](/ci-insights/jobs) |
| 68 | + page for those. |
| 69 | + |
| 70 | +- **Wait time vs. run time.** Wait time is how long a job sits before a runner picks |
| 71 | + it up; run time is how long it executes once started. |
| 72 | + |
| 73 | +- **Health status.** Derived from a runner's success rate and its speed relative to |
| 74 | + its group, so machines that need attention surface on their own. |
| 75 | + |
| 76 | +:::note |
| 77 | + GitHub-hosted runners aren't monitored here. They use a new identity on every run, |
| 78 | + which makes per-runner metrics unreliable. |
57 | 79 | ::: |
0 commit comments