GitLab 18.x Ultimate provides native support for all four DORA metrics via its REST API, giving engineering teams deep insights into the performance and reliability of their software delivery processes.

---

✅ Prerequisites

Before you begin, ensure:

Requirement	Description
GitLab Tier	GitLab Ultimate (SaaS or Self-Managed)
User Role	At least Reporter on the target project/group
API Access	A personal access token with read_api scope
Environments	Deployments to production tier are configured
Incidents (for MTTR/CFR)	Use GitLab’s built-in incident management

---

🧭 Overview of Supported DORA Metrics

Metric	Description
Deployment Frequency	How often code is deployed to production
Lead Time for Changes	Time between MR merge and deployment
Change Failure Rate	Ratio of failed deployments (with incidents) to total deployments
Time to Restore Service	Time from incident creation to resolution

---

🔧 Step 1: Setup Deployments and Environments

1. Define production environments in your CI/CD pipeline:

deploy_prod:
  stage: deploy
  script:
    - ./deploy.sh
  environment:
    name: production
    tier: production

2. Ensure your production deployments are successfully tracked under:
   Project → Operations → Environments

---

🛠 Step 2: Use GitLab’s Incidents (For CFR + MTTR)

• Go to: Project → Monitor → Incidents
• Create incidents manually or via /incident in issues
• Ensure incidents are associated with the correct environment (production)
• Close incidents when resolved

---

🧪 Step 3: Generate DORA Metrics Using REST API

🔸 Project-Level DORA Metrics

GET /projects/:id/dora/metrics

Example Request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.com/api/v4/projects/123456/dora/metrics?metric=deployment_frequency&start_date=2024-01-01&end_date=2024-04-01"
Code language: JavaScript (javascript)

🔸 Group-Level DORA Metrics

GET /groups/:id/dora/metrics

Example Request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  "https://gitlab.com/api/v4/groups/5678/dora/metrics?metric=lead_time_for_changes&interval=daily"
Code language: JavaScript (javascript)

---

📌 Supported API Parameters

Parameter	Description	Default
metric	Required. One of: deployment_frequency, lead_time_for_changes, change_failure_rate, time_to_restore_service	—
start_date	ISO 8601 start date	3 months ago
end_date	ISO 8601 end date	Today
interval	daily, monthly, all	daily
environment_tiers	production, staging, etc.	production

---

📥 Example Responses

[
  { "date": "2024-04-01", "value": 4 },
  { "date": "2024-04-02", "value": 2 }
]
Code language: JSON / JSON with Comments (json)

• value meaning depends on the metric:
  • Deployment Frequency: # of successful deployments
  • Lead Time: Seconds between merge and deploy
  • Change Failure Rate: Ratio (e.g. 0.25 = 25%)
  • MTTR: Seconds taken to resolve incidents

---

📈 Step 4: Visualize & Analyze Metrics

• Metrics appear in Project → Analytics → CI/CD → DORA Metrics (UI available if licensed)
• You can export metrics to:
  • Grafana / PowerBI / Google Sheets
  • GitLab CI pipeline reports or Slack alerts

---

⚙️ Step 5: Automate DORA API Pulls Using GitLab CI Job

Add the following job to your .gitlab-ci.yml file:

dora_metrics:
  stage: report
  script:
    - mkdir -p dora
    - |
      for metric in deployment_frequency lead_time_for_changes change_failure_rate time_to_restore_service; do
        curl --silent --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
          "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/dora/metrics?metric=$metric&start_date=$(date -I -d '30 days ago')&end_date=$(date -I)&interval=daily" \
          > "dora/${metric}.json"
      done
    - echo "✅ DORA metrics saved in the 'dora' directory"
  artifacts:
    paths:
      - dora/
    expire_in: 7 days
Code language: PHP (php)

🔐 CI/CD Variable Required

Key	Value
GITLAB_TOKEN	Your personal access token with read_api

This will generate JSON files in dora/ which can be uploaded to dashboards or emailed/reported as needed.

---

🧠 Best Practices

• Keep production tier tagging consistent for environments
• Use structured commit messages to link MRs to features
• Automate incident creation when pipeline fails in production
• Pull metrics into dashboards to observe trends

---

✅ Summary

DORA Metric	Setup Required	How to Fetch
Deployment Frequency	Deployments with production tier	/dora/metrics?metric=deployment_frequency
Lead Time for Changes	MRs + Production Deployments	/dora/metrics?metric=lead_time_for_changes
Change Failure Rate	Incidents + Deployments	/dora/metrics?metric=change_failure_rate
MTTR	Incident open → close duration	/dora/metrics?metric=time_to_restore_service

---