Deployment Tracking Setup

Enable deployment tracking for DORA metrics

How Coderbuds Tracks Deployments

Coderbuds automatically tracks your deployments by listening to deployment events from GitHub and Bitbucket. To enable this, your CI/CD workflow needs to create deployment environments when deploying.

The key requirement is using a production environment in your workflow. Once configured, Coderbuds will automatically calculate your deployment frequency, lead time, and other DORA metrics.

Set this up with your coding agent

Deploy tracking is a change to a workflow file or a deploy script, so hand the whole job over. This brief carries the rules that are not visible from the repository -- which environment name counts, why the SHA is required, and what should never be reported as production.

Set up Coderbuds deployment tracking for this repository.

WHY THIS MATTERS
Coderbuds reports DORA metrics -- deployment frequency, lead time, change
failure rate, time to restore -- and tells the team which merged pull
requests have not reached production yet. All of it depends on one signal
per finished production deploy, carrying the commit SHA that was deployed.

Pick the route that matches how this repository actually deploys. Inspect
the repo first rather than assuming.

1. GITHUB ACTIONS -- preferred. Nothing secret to store.
   Give the workflow permission to write deployments, and put an
   environment on the job that deploys:

     permissions:
       contents: read
       deployments: write

     jobs:
       deploy:
         environment:
           name: production
         # ... existing steps unchanged

2. BITBUCKET PIPELINES -- mark the production step:

     - step:
         name: "Deploy to Production"
         deployment: production

3. ANYTHING ELSE -- a deploy script, Forge, Envoyer, Laravel Cloud, a
   platform webhook. POST to the Coderbuds tracking webhook as the last
   step of a successful deploy:

     curl -fsS -X POST "$CODERBUDS_DEPLOY_WEBHOOK" \
       -d environment=production \
       -d status=success \
       -d sha="$(git rev-parse HEAD)"

   Ask me for the webhook URL -- I get it from Coderbuds under the
   repository's settings, Production tracking, "Create tracking webhook".
   It is the only credential on that endpoint, so put it in a secret or
   an environment variable, never in a committed file.

RULES YOU CANNOT INFER FROM THE REPO
- The environment name must match the repository's production environment
  in Coderbuds. The default is `production`. If this repo deploys to an
  environment called something else, tell me, because the name has to be
  changed in Coderbuds too or the deploys arrive and count for nothing.
- Always send the deployed SHA. Without it Coderbuds cannot work out which
  pull requests a deploy shipped, so lead time and the undeployed queue
  become estimates rather than facts.
- Report failed deploys as well, with status=failure. Change failure rate
  is only real if the failures arrive.
- Do not report staging, preview or review-app deploys as production.

WHEN YOU ARE DONE
Tell me which route you used, exactly what you changed, and anything still
needed from me -- a secret to set, or an environment name to change in
Coderbuds.

Paste it into Claude Code, Codex, Cursor, or whichever agent you run. The rest of this page is the same information, written for a person.

GitHub Actions Workflow

The easiest way to enable DORA metrics is through a GitHub Actions workflow that uses GitHub's built-in deployment tracking.

Benefits:

  • • Automatic deployment event creation
  • • Built-in environment URL tracking
  • • Status monitoring (pending, success, failure)
  • • Seamless DORA metrics integration
.github/workflows/deploy.yml 
name: Deploy to Production

on:
  push:
    branches: [main]

permissions:
  contents: read
  deployments: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://your-app.com
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Deploy to production
        run: |
          # Add your deployment commands here

Key Configuration:

environment.name Set environment (production, staging)
deployments: write Essential for DORA tracking

Bitbucket Pipelines

If you're using Bitbucket, enable DORA metrics using Bitbucket Pipelines with built-in deployment tracking.

bitbucket-pipelines.yml 
image: node:18

pipelines:
  branches:
    main:
      - step:
          name: "Deploy to Production"
          deployment: production
          script:
            - npm ci
            - npm run build
            - echo "Deploying..."

Verify Your Setup

What to Check:

  • • Deployments appear in your dashboard after successful runs
  • • DORA metrics start calculating (may take a few deployments)
  • • Environment and status information is correct
  • • Pull requests are automatically linked to deployments
View Deployments

Troubleshooting

"No Deployments Found"

This usually means your workflow isn't creating deployment events. Make sure:

  • • GitHub: Your workflow uses environment: in the job configuration
  • • Bitbucket: Your pipeline uses deployment: in the step configuration
  • • Your repository is connected to Coderbuds with the correct permissions

"Deployments found but no production environment"

We found deployments, but they're going to environments other than production. DORA metrics focus on production deployments. Update your workflow to use production as the environment name: 

environment:
  name: production  # Use exactly "production"

GitHub Users: Install the GitHub App

For the best experience, install the Coderbuds GitHub App on your repositories. This enables automatic webhook setup and ensures deployment events are captured in real-time. Visit your repository settings in Coderbuds to check the installation status.

FEATURED

In-Depth Guide

Learn the philosophy behind simple, reliable deployments with real-world examples.

Read: Structuring GitHub Workflows