DORA Metrics Quick Start Guide

Prerequisites

Before you begin, you'll need:

1. DevGrid Account - Sign up at devgrid.io
2. API Key - Generate one from your DevGrid account settings
3. Application Entity - Create at least one application/service entity in DevGrid
4. Entity ID - Note the shortId or id of your application entity

Step 1: Get Your API Key

1. Log in to DevGrid
2. Navigate to Settings → API Keys
3. Click Generate New API Key
4. Copy and save your API key securely (you won't see it again)
5. Store it as an environment variable:
   Bash

   export DEVGRID_API_KEY="your-api-key-here"

Step 2: Identify Your Application Entity

1. In DevGrid, go to Applications or Entities
2. Find the application you want to track
3. Note the Entity ID (or Short ID)
4. Store it as an environment variable:
   Bash

   export DEVGRID_ENTITY_ID="your-entity-id-here"

Step 3: Send Your First Deployment Event

Use this curl command to send a test deployment event:

curl -X POST https://prod.api.devgrid.io/events \
  -H "x-api-key: $DEVGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "event-deploy",
        "timestamp": "2025-10-29T18:30:00Z",
        "entityId": "'"$DEVGRID_ENTITY_ID"'",
        "attributes": {
          "env": "production",
          "status": "success",
          "build_id": "test-build-001",
          "build_commit_sha": "a1b2c3d4e5f6789",
          "description": "Test deployment from Quick Start guide",
          "initiator": "[email protected]"
        }
      }
    ]
  }'

Expected Response

If successful, you'll receive a response like this:

{
  "success": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "event-deploy",
      "entityId": "your-entity-id",
      "blueprintId": "04252f20-4000-470a-a1eb-88bf5bb648d2",
      "timestamp": "2025-10-29T18:30:00Z",
      "accountId": "your-account-id",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_id": "test-build-001",
        "build_commit_sha": "a1b2c3d4e5f6789",
        "description": "Test deployment from Quick Start guide",
        "initiator": "[email protected]"
      },
      "createdAt": "2025-10-29T18:30:15Z"
    }
  ],
  "failures": []
}

Common Errors

401 Unauthorized

{
  "message": "Unauthorized"
}

→ Check that your API key is correct and included in the x-api-key header

400 Bad Request - Entity Not Found

{
  "success": [],
  "failures": [
    {
      "event": {...},
      "reason": "Entity not found"
    }
  ]
}

→ Verify your entityId exists in DevGrid

400 Bad Request - Invalid Format

{
  "success": [],
  "failures": [
    {
      "event": {...},
      "reason": "Invalid event type"
    }
  ]
}

→ Make sure type is exactly "event-deploy" (not "deployment" or "deploy")

Step 4: Verify Your Event

1. Log in to DevGrid
2. Navigate to your application
3. Check the Events tab or Metrics dashboard
4. You should see your deployment event appear

Note: Metrics are calculated daily at UTC midnight, so you may need to wait until the next day to see deployment frequency, lead time, etc.

Step 5: Integrate with Your CI/CD Pipeline

Now that you've verified the API works, integrate it into your deployment pipeline:

For GitHub Actions:

- name: Send Deployment Event
  run: |
    curl -X POST https://prod.api.devgrid.io/events \
      -H "x-api-key: ${{ secrets.DEVGRID_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{
        "events": [{
          "type": "event-deploy",
          "entityId": "${{ vars.DEVGRID_ENTITY_ID }}",
          "attributes": {
            "env": "production",
            "status": "success",
            "build_id": "${{ github.run_id }}",
            "build_commit_sha": "${{ github.sha }}",
            "build_url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
            "initiator": "${{ github.actor }}"
          }
        }]
      }'

See CI/CD Integration Examples for more platforms.

Step 6: Configure Additional Integrations

To unlock all DORA metrics, you'll need to configure additional integrations:

For Lead Time for Change

• Connect your GitHub/GitLab/Bitbucket account
• DevGrid will automatically pull commit and PR data
• Ensure build_commit_sha in your deployment events matches actual commit SHAs

For Change Failure Rate

• Connect your incident management system (ServiceNow, PagerDuty, etc.)
• Add change_id to deployment events
• Link incidents to deployments in your incident system
• See ServiceNow Integration Guide

For Mean Time to Restore

• Connect your incident management system
• DevGrid will calculate MTTR from incident open/close timestamps

Environment URLs

• Development/Staging: https://api.dev.devgrid.io/events
• Production: https://prod.api.devgrid.io/events

Choose the appropriate endpoint based on your DevGrid account environment.