Since launching MergeQueue, we have been building tools to improve developers’ workflows. And as with any product serving developers, APIs become a very core part of the user experience. We are excited to announce the beta launch of API and webhooks on MergeQueue. We will cover some of the basics in this post. The detailed description can be found in our MergeQueue documentation.
API
The first use-case we are launching with APIs is to fetch MergeQueue analytics. Following some of the modern RESTful API architectures, we are using HTTP basic authentication to authenticate and using RESTful objects to fetch and update.
Analytics API
MergeQueue analytics provides great insights into the developer workflow and helps understand the bottlenecks. The metrics can be accessed through the MergeQueue analytics dashboard.
With the Analytics API, we are providing the same capabilities that can be exported to any other data visualization tool. MergeQueue Analytics API object represents each metrics aggregated by the date and can be queried using any start and end date window. The following metrics are supported in the Analytics API object:
- time_in_queue – The time in seconds a PR spends in the queue before it is merged by the MQ bot. Represented as average, minimum, maximum (p100), p50, p75, p90.
- mergequeue_usage – what fraction of the PRs are merged by the MQ bot vs merged manually.
- blocked_reason – breakdown of failure reasons when MQ bot identifies a PR as failed.
- sync_frequency – how many times a PR is updated from the base branch (usually main or master) before it’s merged. . Represented as average, minimum, maximum (p100), p50, p75, p90.
Webhooks
Using webhooks, you can subscribe to events managed by MergeQueue bot. Using webhook configuration in MergeQueue dashboard, you can subscribe to all or a subset of the supported event actions. Each webhook is associated with a PullRequest, and the webhook payload contains the associated information. There are 7 event actions supported in standard mode of MergeQueue: opened, labeled, queued, dequeued, top_of_queue, merged, and blocked. The details for the events can be found in the documentation. In addition, there are two events in batch mode – stuck and reset.
One of the key use cases that we identified through our users is the handling of PullRequests that failed to merge. In such cases, we send a webhook with the action blocked along with a status_code providing the reason why this was blocked. This data can be used to take specific action on the PullRequest. For instance, if the PR was identified as blocked due to merge conflict the developer can be notified to fix the conflict manually, or if the PR was blocked due to missing owner review the owner / reviewer can be notified.
Future Expansion
We are really excited about launching the API and webhooks as this opens the doors for creative configurations that developers can set up in their internal engineering processes. This will also serve as a guiding compass for us as we build additional API capabilities.