Time to Merge Metric

Definition

The Time to Merge Metric measures the time between the first approval of a pull request (PR) and when the PR is merged.

This metric helps engineering teams understand how quickly approved changes are finalized and integrated into the target branch. It can highlight delays caused by additional changes, merge conflicts, required checks, or other steps that occur after the first approval.

Important: For approved PRs, Time to Merge starts at the first approval, not the final or most recent approval. Subsequent approvals do not reset the starting timestamp.

Between the first approval and merging of a PR, several activities may take place, depending on the team's workflow and tools. Common activities include:

Addressing Final Comments or Changes
- Even after the first approval, the author may need to address outstanding feedback or implement additional changes.
Rebasing or Resolving Merge Conflicts
- If updates to the base branch (for example, main or develop) conflict with the PR, the author must rebase or resolve the conflicts before merging.
Executing CI/CD Pipelines
- Automated checks may need to complete before merging, including:
  - Unit tests
  - Integration tests
  - Code style and linting checks
  - Security scans

These steps help maintain code quality, minimize disruptions, and ensure changes are integrated successfully.

Why Is This Metric Important?

Short Time to Merge: Generally indicates a smooth process with effective collaboration, completed checks, and minimal blockers after approval.
Long Time to Merge: May indicate outstanding changes, merge conflicts, delayed checks, or other activities preventing an approved PR from being merged.
Team Productivity: Helps teams understand how efficiently approved changes progress toward integration.
Bottleneck Identification: Highlights delays between the first approval and merge, helping teams identify opportunities to improve their workflow.
Code Quality and Collaboration: Encourages teams to establish clear approval requirements and efficient merging practices.
Release Velocity: Reducing unnecessary delays after approval can help accelerate development and release cycles.

How to Improve Time to Merge

Create Smaller, Focused PRs: Smaller changes are generally easier to validate, maintain, and merge.
Improve Review Cycles: Resolve outstanding feedback promptly and establish clear expectations for when a PR is ready to merge.
Automate Checks: Use automated testing, linting, and security checks to identify issues early and reduce merge delays.
Improve Communication: Ensure developers and reviewers understand remaining requirements and merge blockers.
Reduce Merge Conflicts: Keep branches up to date and integrate changes frequently to reduce conflicts.

Tracking the Time to Merge metric helps engineering teams identify and reduce delays between approval and integration, improving development workflows and delivery efficiency.

Calculation

The Time to Merge calculation depends on whether a PR received a review or approval before it was merged.

Branch Merged Without a PR

If a branch is merged without a pull request, no Time to Merge metric is calculated.

PR Merged Without a Review

If a PR is merged without any review activity, Time to Merge is 0.

Time to Merge = 0

PR Merged Without Approval

If a PR receives review activity but is merged without approval, Time to Merge is equal to its Review Time.

Time to Merge = Review Time

In this scenario, Review Time is the duration between the PR becoming ready for review and the merge.

PR Approved and Then Merged

If a PR receives one or more approvals before being merged, Time to Merge is calculated using the first approval timestamp.

Time to Merge = Time of PR Merge - Time of First Approval

Important: If a PR receives multiple approvals, the calculation uses the first approval. Later approvals do not replace the original approval timestamp or restart Time to Merge.

Examples for Context

One Review With Approval

A PR receives one review with approval and is subsequently merged. Time to Merge measures the duration between that first approval and the merge.

Multiple Reviews Before Approval

A PR may undergo multiple reviews before receiving its first approval. Earlier review activities may include comments or requested changes.

The Time to Merge calculation starts at the first approval, regardless of how many reviews occurred beforehand. Any subsequent approvals do not reset the starting timestamp.

Event	Review Activity	Effect on Time to Merge
Review 1	Reviewer comments or requests changes.	No approval has been recorded.
Review 2	Reviewer provides additional feedback.	No approval has been recorded.
First Approval	A reviewer approves the PR.	Starts Time to Merge.
Additional Approval	Another reviewer approves the PR.	Does not reset Time to Merge.
Merge	The PR is merged.	Ends Time to Merge.

Time to Merge = Merge - First Approval

Note: Review 1 and Review 2 represent review activities without approval, such as comments or changes requested. Only the first approval starts Time to Merge.

Only Approval Exists

If a PR's first review activity is an approval, Time to Merge starts at that approval and ends when the PR is merged.

Review Exists Without Approval

If a PR receives review activity but is merged without an approval, Time to Merge is equal to Review Time, measured from when the PR became ready for review until it was merged.

No Review Exists