Using Datadog with Mergify

The Datadog integration pushes your merge queue metrics into your own Datadog account. Everything on the merge queue statistics page is available as a Datadog metric, so you can graph queue health next to your own service metrics and alert on it.

The integration is official and ships as a Mergify tile in Datadog’s integration catalog. Mergify writes the metrics to Datadog for you. There is no agent to install and nothing to run in your CI.

• A Datadog account, and permission to authorize integrations in it.

• On the Mergify side, a plan that includes the Datadog integration, plus the GitHub organization Owner role or the Integrations Admin delegated role.

1. Install the Mergify tile from Datadog’s integration catalog and click Connect Accounts. The connection starts on the Datadog side, so the Connect Your Datadog Account button on the Mergify dashboard’s Integrations → Datadog page opens Datadog’s catalog rather than connecting from Mergify.

   

2. Authorize Mergify from the Datadog site your organization uses. Mergify supports US1, US3, US5, EU1, US1-FED, and AP1, and connects to whichever one you start from. Datadog then asks which GitHub organization to connect. Mergify creates an API key scoped to the integration and starts pushing metrics to that site.

3. Choose what to monitor. For each repository, select the merge queue base branches you want metrics for: the branches your queued pull requests target, such as main or a release branch.

To switch the Datadog site your metrics go to, connect Mergify again from the site you want to move to, whether you are changing region or consolidating on a different Datadog organization. You do not need to know which site you are on today: reconnecting replaces the previous connection, whatever it was.

1. Sign in to Datadog on the site you are moving to.

2. In that account, install the Mergify tile and click Connect Accounts, exactly as you did when you first connected. There is no other way in: Mergify has no control that starts the change, and no API or CLI equivalent.

3. Choose the same GitHub organization as before, and authorize Mergify. The site you end up on is the one you started from, so there is nothing else to pick.

The Datadog permissions in Prerequisites apply again here, but to the Datadog organization you are moving to; the Mergify role requirement is unchanged.

Metrics start arriving on the new site at the next publication, and the old site stops receiving new points at the same moment. If you start the authorization and do not finish it, nothing changes: the previous connection stays in place until the new one completes.

Your monitored repositories and their base branches are preserved. They belong to your GitHub organization rather than to the Datadog connection, so you do not have to select them again.

What stays behind on the old site:

• The metrics already sent there. Mergify publishes new points from the moment you reconnect; it does not copy history to the new site.

• Anything you built on those metrics. Dashboards cloned from the Mergify tile and any monitors you created live in the old Datadog organization. Recreate them on the new site.

• The API key Mergify created. Reconnecting creates a new key on the new site and does not revoke the old one, so delete it yourself in the old Datadog organization once the switch is done.

To stop sending metrics without disconnecting anything, remove every repository from the integration page in the Mergify dashboard. Metrics only cover the repositories you select, so an empty list stops them. The connection and the API key stay in place, ready if you add a repository back.

To disconnect entirely, delete the API key Mergify created in your Datadog organization. Mergify checks that key every minute and drops the connection as soon as it stops working, so nothing is left behind on either side. This is the only route that removes both halves, and it is done from Datadog: the Mergify dashboard has no disconnect control, because deleting the connection there would leave the API key live in your Datadog account.

Removing the key needs permission to manage API keys in Datadog. If that is someone else in your organization, ask them to delete it; clearing the repository list stops the metrics in the meantime.

Every metric is published every 5 minutes, and each point covers the 5-minute window it represents.

Every metric carries these tags:

Metrics submitted as count are event tallies that Datadog sums exactly over any time range. Metrics submitted as gauge are peak values within the window.

Both outcome and exit_reason are success when the pull request merged or its checks passed. Otherwise they name the reason the pull request left the queue or its checks were aborted, such as checks_failed or pr_dequeued. The integration’s README lists every value.

skip_intermediate_results.batches_saved counts the batches that merged because a later batch containing their changes had already passed, so each one is a CI run the queue avoided. It only moves when skip_intermediate_results is enabled on the queue.

The duration and size metrics ship as a .sum and a .count rather than a pre-computed average, so Datadog can recompute the real average over whatever time range you graph. Divide a family’s own sum by its own count:

sum:mergify.queue.total_queue_time.sum{$repository} / sum:mergify.queue.total_queue_time.count{$repository}

The same shape gives you average CI runtime (mergify.queue.ci_runtime.*) and average batch size (mergify.queue.batch_size.*).

The share of failed checks that passed when retried:

sum:mergify.queue.checks_retries.recovered{$repository} / (sum:mergify.queue.checks_retries.recovered{$repository} + sum:mergify.queue.checks_retries.not_recovered{$repository})

Total queued time splits into CI runtime plus three kinds of waiting:

mergify.queue.breakdown.ci_runtime.sum   # running CI
mergify.queue.idle.capacity.sum          # waiting for a free check slot
mergify.queue.idle.schedule.sum          # waiting for a schedule to open
mergify.queue.idle.freeze.sum            # waiting for a freeze to lift

Graphed together as a stacked area, they show what your queue is actually waiting on. Divide any of them by mergify.queue.idle.count for a per-pull-request average.

Because the three idle.* metrics are pure waiting time, sum:mergify.queue.idle.*.sum gives you total wasted time without counting CI.

The Mergify tile ships a Mergify - Merge Queue Stats dashboard that mirrors the merge queue statistics page. In Datadog, search for mergify in your account’s integration catalog, open the Mergify tile, and find the dashboard under the Monitoring Resources tab. Clone it to adapt it to your own repositories, or build your own from the metrics above.

Since the metrics are ordinary Datadog metrics, you can alert on them with monitors. Useful ones to start with:

• mergify.queue.size.max staying above a threshold, which usually means CI capacity is the bottleneck.

• Average queued time trending up week over week.

• Check retry recovery rate dropping, which points at genuinely broken tests rather than flaky ones.

• mergify.queue.exit_reason counting anything other than success, which means pull requests are leaving the queue without merging.

• Monitoring your merge queue: what each metric means and how to read it.

• The Mergify tile on Datadog: setup from the Datadog side and the bundled dashboard.