GitLab can calculate delivery and flow measures only from records it can connect. A successful pipeline isn't necessarily a production deployment. An alert isn't necessarily a closed incident. An issue that never reaches a Value Stream Analytics end event isn't part of that stage's completed-work result.
Before teams compare results or set improvement targets, confirm that the records in GitLab describe the delivery process closely enough to support the intended decision. Begin with a representative change, deployment, and incident. Follow each through GitLab, compare it with what happened in the delivery and incident tools, and resolve gaps before expanding the report.
Define the decision and included work
Start by writing down the decision you want to make. “Improve delivery performance” is too broad. You might want to help an application owner decide whether to address review delays or release batching first.
To interpret the results later, keep a note of:
- The application, service, or product included in the result.
- What the organization considers a production deployment and a production incident.
- The person or team that owns the scope and approves changes to it.
- The people responsible for deployment and incident integrations.
- The release path and any tool outside GitLab.
- The business question the measure is expected to answer.
You can apply these checks to the records you already have. GitLab's DORA reporting1 and Value Stream Analytics2 provide views over those records, with different feature availability. Choose a view that answers the question rather than changing your delivery process just to populate it.
The following table helps identify which records the measure needs and what to compare with real work.
| Measure | Records behind it | What to check in a real example |
|---|---|---|
| Deployment frequency | Successful deployments to production environments | The destination, revision, result, and completion time agree with a known release |
| Lead time for changes | Merged changes associated with successful production deployments | GitLab connects the merge request to the deployed revision and measures from merge time |
| Time to restore service | GitLab incident creation and closure times | Opening and closure agree with the interruption and restoration of service |
| Change failure rate | Successful production deployments and GitLab incidents | Both sets describe the same service and period, without duplicate incident records |
| Value Stream Analytics stage time | Items with the selected start and end events | Both events represent the team's actual work; still-open items are reviewed separately |
| Value Stream Analytics lifecycle measures | The issue, commit, merge request, pipeline, deployment, and closure records used by the measure | The links and events let GitLab follow a completed change through the expected path |
The DORA metrics documentation defines the records and timestamps used for each measure. The Value Stream Analytics documentation explains stage events and scope behavior. Use those definitions when local terminology differs from GitLab terminology.
Follow a change you can explain
Choose a project whose release and incident processes the team can explain. Begin with how a change reaches production rather than a performance category or target.
Select a recent change that participants can explain. Note its request, merge request, deployed revision, production destination, and any related incident. This becomes the first sample.
Make the deployment record match the release
Start with deployment frequency because its production deployment records also support lead time for changes. Confirm that the real release creates a successful production deployment containing the revision customers received and its completion time. See Environments and deployments for current behavior.
If GitLab CI/CD performs the release, connect the production environment to the job that knows whether the release completed. Avoid creating a deployment record from a build or test job solely to populate a report.
If another system performs the release, it needs to send GitLab the deployment, final outcome, and deployed revision. See DORA metrics without GitLab CI/CD, external deployment tools, and the Deployments API for the integration options.
For an external deployment, create the GitLab deployment when the release begins and update it to success or failed promptly when the release ends. The Deployments API doesn't accept a caller-supplied finish time, so a delayed final update or a historical backfill can make GitLab record the wrong completion period. Establish a documented coverage start instead of backfilling old releases as if they had completed now.
Reconcile a known release before reviewing a trend. Compare the production destination, deployed revision, result, and completion time. If they disagree, wait to use the result for a decision until the discrepancy is understood and the integration gap has an owner.
Connect merged changes to production
After deployment records reconcile, follow a merged change into production. Confirm that the deployed revision contains the merge request commits and GitLab associates the change with that deployment. Compare its timestamps with the lead time calculation.
Release trains, long-lived release branches, and cherry-picks can change how a merge request reaches production. Document that path and test it with a representative change. If GitLab can't follow the association reliably, use the result only within its understood context rather than comparing it with a project that follows a different release model.
Make incident records describe service restoration
Introduce time to restore service and change failure rate only after the team defines a production incident. Decide where incidents begin, who closes them, and how repeated alerts relate to an existing incident. See incident management for supported records and integrations.
Check the calculation assumptions against the local incident model. GitLab treats incidents in the measured project as production incidents. Time to restore service assumes a strict one-to-one relationship between incidents and deployments. Change failure rate doesn't link an incident directly to a deployment, and duplicate incident records can change the result. If the local model doesn't fit those assumptions, record the limitation or defer the affected measure.
Compare a representative GitLab incident with its incident-management source and confirm that service restoration closes it. Review the deployments and incidents contributing to the result. Record reporting changes alongside the trend because coverage can change a metric even when service behavior has not.
If the organization keeps incidents in another tool, decide whether to send the incident lifecycle to GitLab or defer the two incident-dependent measures. Retaining incidents only outside GitLab may still support local analysis, but it doesn't prepare the GitLab records required for these DORA results. See GitLab's guidance for DORA metrics with external incident tools.
Look for work the stage result leaves out
Choose stage events that the workflow already produces. Follow a completed item and confirm that it reaches each intended end event. Also review work that is still open, blocked, or missing links.
Value Stream Analytics includes an item in a stage result only after the item reaches that stage's end event. Missing or unfinished work can therefore reduce coverage without appearing as a slower completed item. A lower stage median doesn't by itself show improvement when the amount of unfinished work has grown. Review the stage item list and work in progress beside the result. The Value Stream Analytics lifecycle documentation is the authority for event and completion behavior.
Decide which results you can act on
Review the examples with the people who will use the report. When the records agree with real work, use the measure for the question it can answer. If some work is missing or follows a different path, narrow the comparison or repair the integration before drawing a broader conclusion.
For example, a team may confirm that GitLab records its releases correctly but discover that its incident tool doesn't send closure events. It can use deployment frequency to understand its release pattern while improving the incident integration. There's no need to wait for every report to be complete, or to treat the incomplete ones as reliable.
Expand only when another project can repeat the reconciliation and explain its rules. Recheck after changes to the delivery path, incident integration, project structure, or GitLab version.
Once the records are sound, Choosing measures that guide improvement helps you decide what to track during a change and which unwanted effects to watch for.
Tradeoffs
Comparable scope versus broad coverage
A narrow scope is easier to explain and reconcile, but it may omit important parts of a product. A broad group result gives leaders wider coverage, but can combine different release models and production responsibilities. Begin where ownership and records are clear, then add projects with documented differences. Compare teams only when the measures answer the same question and use compatible production rules.
Native deployment records versus external integrations
GitLab CI/CD can keep the release job and deployment record close together. An external deployment tool may better fit a pull-based or specialized delivery model, but someone will need to maintain the integration. Choose based on how you deliver software. In either case, check that the GitLab deployment agrees with the system that completed the production release.
External deployment tracking provides deployment history and DORA data, but it doesn't give an external release the same operational controls as a GitLab CI/CD deployment. GitLab can't use external deployments with protected environments, deployment approvals, deployment safety, or deployment rollback. Keep those controls in the external deployment system and review the current external deployment guidance before choosing that path.
Incident coverage versus trend continuity
Improving incident capture may increase incident-dependent measures at first. That can represent better reporting rather than declining reliability. Preserve a note about changes to incident definitions or integrations, and avoid comparing periods that use materially different rules without that context.
Completed-work measures versus all work
End-event measures answer how long completed items took. They don't, by themselves, answer how much work is stalled or never reaches completion. Pair Value Stream Analytics stage results with work-in-progress and missing-link reviews so that faster completed work doesn't hide a growing queue.
Correcting records versus preserving published results
Repairing a missed deployment or forgotten incident closure can improve the source data, but it may also change a result that stakeholders have already seen. Define who may make corrections, record the reason, and tell report consumers when a prior result has changed. This keeps a data repair from being mistaken for a delivery improvement.
Further Reading
Notes
-
GitLab's DORA reporting is available in Ultimate. The same questions about complete, consistent records apply when you calculate delivery measures in another reporting tool. ↩
-
Value Stream Analytics includes predefined project stages in Free. Group reporting, custom value streams, and custom stages are available in Premium and Ultimate. ↩
- DORA metrics explains the calculations and assumptions to use when reconciling a report with source records.
- DORA metrics API shows how to retrieve results for your own reporting tools.
- Environments and deployments explains how to configure the production environments and deployment jobs behind the measures.
- External deployment tools walks through sending deployment outcomes to GitLab; the Deployments API provides the request parameters for the integration.
- Incident management helps you connect incident creation, response, and closure to the records used for stability reporting.
- Value Stream Analytics explains how to configure stages and inspect their included work.