Sending Deployment Events

Understanding Deployment Events
Product Workflows
Integration Examples
Best Practices

Understanding Deployment Events

What Are Deployment Events?

Deployment events are the foundation of DevGrid's DORA metrics. Each time your application deploys, you send an event to DevGrid's API containing metadata about that deployment. DevGrid uses these events to calculate:

Deployment Frequency - How often you deploy
Lead Time for Change - Time from commit to production (requires build_commit_sha)
Change Failure Rate - Percentage of deployments causing incidents (requires change_id)
Mean Time to Restore - Time to recover from failures (requires change_id)

Event Lifecycle in DevGrid

Event Sent - Your CI/CD pipeline sends a deployment event via POST to /events
Event Validated - DevGrid validates the event structure and authentication
Event Stored - Event is persisted with timestamp and attributes
Metrics Calculated - Daily at UTC midnight, metrics are recalculated based on all events
Dashboards Updated - Your DORA metrics appear in DevGrid dashboards

Event Anatomy

Every deployment event has two parts:

Required Fields:

{
  "type": "event-deploy",
  "entityId": "your-app-id",
  "attributes": {
    "env": "production",
    "status": "success"
  }
}

Recommended Fields for Full DORA Metrics:

{
  "type": "event-deploy",
  "entityId": "your-app-id",
  "attributes": {
    "env": "production",
    "status": "success",
    "build_commit_sha": "a1b2c3d4",    // Required for Lead Time
    "change_id": "CHG0012345",          // Required for CFR and MTTR
    "build_id": "build-123",            // Useful for debugging
    "build_url": "https://...",         // Links to your CI/CD
    "description": "Deploy v2.1.0",     // Human context
    "initiator": "[email protected]"     // Who triggered it
  }
}

What Happens After You Send an Event

Once DevGrid receives your event:

Immediate Response - You get a 201 Created response with the stored event
Event Appears in UI - View it in DevGrid → Events → Deployment Events
Metrics Update Next Day - At UTC midnight, DORA metrics recalculate
Lead Time Calculation - DevGrid fetches commit data from your connected GitHub/GitLab
Incident Linking - If you included change_id, DevGrid links to ServiceNow incidents

Important: Metrics are not real-time. They update once daily at UTC midnight to ensure consistent calculations across timezones.

Product Workflows

Workflow 1: Basic Single-Environment Deployment

The simplest workflow tracks production deployments only.

What you send:

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",
      "entityId": "my-app",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_commit_sha": "a1b2c3d4"
      }
    }]
  }'

What DevGrid calculates:

Deployment Frequency (from all events with env: production)
Lead Time for Change (from build_commit_sha + version control data)

To verify:

Check DevGrid UI → Events (event should appear within seconds)
Wait until next day after UTC midnight
Check DevGrid UI → Metrics → Deployment Frequency and Lead Time

Workflow 2: Multi-Environment Tracking

Track deployments across dev, staging, and production.

Key principle: Use consistent environment names across all deployments.

Good:

"env": "production"    // Always lowercase, always full word
"env": "staging"
"env": "development"

Bad:

"env": "prod"          // ❌ Inconsistent with "production"
"env": "Production"    // ❌ Different case
"env": "dev"           // ❌ Then later "development"

Filtering metrics by environment:

DevGrid dashboards let you filter by env attribute
Each environment has separate Deployment Frequency
Lead Time typically only tracked for production

Workflow 3: Complete DORA Metrics with Incident Tracking

To calculate all four DORA metrics, you need to link deployments to incidents.

Step 1: Send deployment with change_id

{
  "type": "event-deploy",
  "entityId": "my-app",
  "attributes": {
    "env": "production",
    "status": "success",
    "build_commit_sha": "a1b2c3d4",
    "change_id": "CHG0012345",           // ServiceNow Change Request ID
    "description": "Deploy v2.1.0"
  }
}

Step 2: Connect ServiceNow integration

Follow ServiceNow Integration Guide
DevGrid will automatically link incidents to deployments via change_id

Step 3: Track incidents

When an incident (INC) references a change (CHG), DevGrid links them
Change Failure Rate = deployments with linked incidents / total deployments
MTTR = time from incident creation to incident resolution

Data flow:

CI/CD Pipeline → DevGrid (deployment event with change_id)
ServiceNow → DevGrid (incidents linked to change_id)
DevGrid → DORA Metrics (CFR and MTTR calculated)

Workflow 4: Failed Deployments

Always track failed deployments to maintain accurate metrics.

When deployment fails:

{
  "type": "event-deploy",
  "entityId": "my-app",
  "attributes": {
    "env": "production",
    "status": "failed",                 // Track failures
    "build_commit_sha": "a1b2c3d4",
    "description": "Deployment failed: database migration error"
  }
}

How DevGrid handles failures:

Failed deployments do NOT count toward Deployment Frequency
They help identify deployment reliability issues
Visible in DevGrid Events view for debugging

Workflow 5: Rollbacks

Rollbacks count as deployments.

When rolling back:

{
  "type": "event-deploy",
  "entityId": "my-app",
  "attributes": {
    "env": "production",
    "status": "success",
    "build_commit_sha": "previous-working-sha",
    "description": "Rollback to v2.0.5 due to incident INC0045678",
    "change_id": "CHG0012346"
  }
}

Why this matters:

Rollbacks count as successful deployments (you deployed working code)
They increase Deployment Frequency
If linked to incident, they help calculate MTTR (time to restore)

Workflow 6: Hotfixes

Track emergency hotfixes separately from regular deployments.

Hotfix deployment:

{
  "type": "event-deploy",
  "entityId": "my-app",
  "attributes": {
    "env": "production",
    "status": "success",
    "build_commit_sha": "hotfix-sha",
    "description": "Hotfix: Critical security patch CVE-2025-1234",
    "change_id": "CHG0012347",
    "deployment_type": "hotfix"         // Custom attribute for filtering
  }
}

Why track hotfixes:

Understand percentage of hotfix vs. regular deployments
Measure impact on Deployment Frequency
Track if hotfixes are becoming more/less frequent over time

Workflow 7: Historical Data Backfill

Import past deployments to establish baseline metrics.

Backfill pattern:

# Send events with historical timestamps
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-01-15T14:30:00Z",    // Historical date
      "entityId": "my-app",
      "attributes": {
        "env": "production",
        "status": "success",
        "build_commit_sha": "historical-sha"
      }
    }]
  }'

Best practices for backfill:

Extract deployment history from CI/CD logs or version control tags
Send events in chronological order (oldest first)
Include as many attributes as available (commit SHA, change ID, etc.)
Wait for next UTC midnight for metrics to recalculate

Integration Examples

Prerequisites

Before integrating, you'll need:

DevGrid API Key - Generate from DevGrid Settings → API Keys
Entity ID - The ID of your application/service in DevGrid
Environment Variables - Store these securely in your CI/CD platform:
- DEVGRID_API_KEY (secret)
- DEVGRID_ENTITY_ID (can be non-secret)

Generic Bash Template

Use this template for any CI/CD platform:

#!/bin/bash
# Generic DevGrid deployment event sender

# 1. Set variables (from CI/CD platform environment)
DEVGRID_API_KEY="${DEVGRID_API_KEY}"
DEVGRID_ENTITY_ID="${DEVGRID_ENTITY_ID}"
DEPLOYMENT_ENV="production"
BUILD_ID="${BUILD_ID:-unknown}"
COMMIT_SHA="${COMMIT_SHA:-unknown}"
BUILD_URL="${BUILD_URL:-unknown}"
INITIATOR="${INITIATOR:-system}"

# 2. Deploy your application
./deploy.sh

# 3. Capture deployment status
DEPLOY_STATUS=$?

# 4. Determine event status
if [ $DEPLOY_STATUS -eq 0 ]; then
  EVENT_STATUS="success"
  DESCRIPTION="Deployment successful"
else
  EVENT_STATUS="failed"
  DESCRIPTION="Deployment failed"
fi

# 5. Send event to DevGrid
RESPONSE=$(curl -s -w "\n%{http_code}" -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\",
      \"entityId\": \"$DEVGRID_ENTITY_ID\",
      \"attributes\": {
        \"env\": \"$DEPLOYMENT_ENV\",
        \"status\": \"$EVENT_STATUS\",
        \"build_id\": \"$BUILD_ID\",
        \"build_commit_sha\": \"$COMMIT_SHA\",
        \"build_url\": \"$BUILD_URL\",
        \"description\": \"$DESCRIPTION\",
        \"initiator\": \"$INITIATOR\"
      }
    }]
  }")

# 6. Check DevGrid response (optional)
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
BODY=$(echo "$RESPONSE" | sed '$d')

if [ "$HTTP_CODE" -eq 201 ]; then
  echo "✓ Successfully sent deployment event to DevGrid"
else
  echo "⚠ Warning: Failed to send event to DevGrid (HTTP $HTTP_CODE)"
  echo "$BODY"
  # Continue anyway - don't fail deployment if DevGrid notification fails
fi

# 7. Exit with original deployment status
exit $DEPLOY_STATUS

GitHub Actions Example

Minimal example showing how to adapt the bash template:

name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Deploy application
        run: |
          echo "Deploying to production..."
          # Your deployment commands here

      - name: Send deployment event to DevGrid
        if: always()  # Send event even if deployment fails
        run: |
          STATUS=${{ job.status == 'success' && 'success' || 'failed' }}

          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": "'$STATUS'",
                  "build_id": "${{ github.run_id }}",
                  "build_commit_sha": "${{ github.sha }}",
                  "build_url": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}",
                  "description": "Deploy ${{ github.ref_name }}",
                  "initiator": "${{ github.actor }}"
                }
              }]
            }'

Adapting to Other CI/CD Platforms

The bash template works with any platform that supports shell commands. Here's what you need to map:

DevGrid Field	GitHub Actions	GitLab CI	Jenkins	CircleCI	Azure DevOps
`build_id`	`${{ github.run_id }}`	`$CI_PIPELINE_ID`	`$BUILD_NUMBER`	`$CIRCLE_BUILD_NUM`	`$(Build.BuildNumber)`
`build_commit_sha`	`${{ github.sha }}`	`$CI_COMMIT_SHA`	`$GIT_COMMIT`	`$CIRCLE_SHA1`	`$(Build.SourceVersion)`
`build_url`	`${{ github.server_url }}/...`	`$CI_PIPELINE_URL`	`$BUILD_URL`	`$CIRCLE_BUILD_URL`	`$(System.TeamFoundation...)`
`initiator`	`${{ github.actor }}`	`$GITLAB_USER_EMAIL`	`$BUILD_USER_ID`	`$CIRCLE_USERNAME`	`$(Build.RequestedFor)`

To integrate with your platform:

Copy the bash template
Replace variable references using the table above
Store DEVGRID_API_KEY as a secret in your CI/CD platform
Add the script after your deployment step

Best Practices

1. Event Attribute Completeness

Always include:

✅ env - Environment name (production, staging, etc.)
✅ status - "success" or "failed"
✅ build_commit_sha - Required for Lead Time calculation

Include for full DORA metrics:

✅ change_id - ServiceNow Change Request ID for CFR and MTTR
✅ build_id - Helps debugging and linking to CI/CD
✅ build_url - Quick link to build details
✅ description - Human-readable context
✅ initiator - Who/what triggered the deployment

Avoid:

❌ Omitting build_commit_sha (breaks Lead Time)
❌ Omitting change_id (can't calculate CFR or MTTR)
❌ Using inconsistent environment names

2. Environment Naming Consistency

DO:

Use lowercase environment names
Use full words: "production", "staging", "development"
Document your naming convention in a team wiki
Use the same names across all applications

DON'T:

Mix "prod" and "production"
Use different cases: "Production" vs "production"
Abbreviate inconsistently: "dev" vs "development"

Why this matters: DevGrid filters and groups metrics by exact env string match. Inconsistent naming splits your data.

3. Error Handling That Doesn't Block Deployments

Golden Rule: DevGrid notifications should NEVER cause your deployment to fail.

Good pattern:

# Send event, capture result, log warnings, but don't exit on failure
if ! curl -X POST ...; then
  echo "Warning: Failed to notify DevGrid"
fi
# Continue with deployment

Bad pattern:

# This will fail your deployment if DevGrid is unreachable
curl -X POST ... || exit 1

Why this matters: Your deployments are more important than metrics. If DevGrid API is temporarily unavailable, your deployment should still succeed.

4. Timing Considerations