← All posts
· 3 min read ·
SalesforceCopadoDevOpsTypeScriptOpen Source

copado-pipeline-inspector: Visibility Into Your Copado Pipelines

A CLI to query Copado pipeline execution history, promotion success rates, and user story throughput directly via the Salesforce REST API - because Copado's built-in reporting isn't enough.

Abstract data flow visualization representing a DevOps pipeline

Copado gives you pipeline automation, but its reporting surface is thin. You can see if the last promotion succeeded or failed. You can’t easily answer questions like: what’s our promotion success rate over the last 30 days? Which user stories are stuck in QA? Which developer’s branches have the most deployment failures?

copado-pipeline-inspector queries the Copado data model via the Salesforce REST API and surfaces answers to those questions in a terminal or as structured JSON you can pipe into dashboards.

The Visibility Gap

Copado stores everything in Salesforce custom objects:

  • copado__Deployment__c - individual deployment records
  • copado__User_Story__c - user stories with status and environment
  • copado__Promotion__c - promotions linking stories to pipeline stages
  • copado__Pipeline__c and copado__Pipeline_Connection__c - pipeline topology

The data is all there. But surfacing it requires writing SOQL queries against a model that isn’t well documented, authenticating via Connected App, and formatting the results usefully. That friction means most teams never look at it.

What the CLI Provides

# Pipeline health summary for the last 30 days
copado-inspect pipeline --name "Commerce Cloud" --days 30

# User stories by status across all environments
copado-inspect stories --status In_Progress,QA

# Promotion history with success/failure breakdown
copado-inspect promotions --pipeline "Commerce Cloud" --days 14

# Stories promoted by a specific developer
copado-inspect stories --developer jane.smith@example.com

# Export everything as JSON
copado-inspect pipeline --name "Commerce Cloud" --format json > report.json

Sample output from pipeline:

Pipeline: Commerce Cloud (last 30 days)
═══════════════════════════════════════
Promotions:     47 total  |  38 passed (80.9%)  |  9 failed
Avg duration:   8.4 min   |  p95: 22 min
Blocked stories: 3 (>5 days in same environment)

Stage breakdown:
  Dev → QA:     19 promotions  87% success
  QA → UAT:     16 promotions  81% success
  UAT → Prod:   12 promotions  75% success

Authentication

The CLI uses the Salesforce REST API with OAuth 2.0 username/password flow (suitable for CI) or a stored session token for interactive use. Credentials are configured once:

copado-inspect auth --instance https://myorg.my.salesforce.com \
  --client-id <connected-app-id> \
  --client-secret <connected-app-secret> \
  --username ops@myorg.com \
  --password <password+security-token>

Credentials are stored in ~/.copado-inspector/config.json. The CLI refreshes tokens automatically.

SOQL Under the Hood

The interesting engineering challenge was building efficient SOQL queries against Copado’s object model. A naive approach would issue one query per object, but that hits API limits fast for large orgs.

The solution is relationship queries that traverse the Copado model in a single call:

SELECT
  Id, Name, copado__Status__c, copado__Environment__c,
  copado__Developer__r.Name,
  (SELECT Id, copado__Status__c, copado__Promotion__r.Name
   FROM copado__Promotion_User_Stories__r
   ORDER BY CreatedDate DESC LIMIT 5)
FROM copado__User_Story__c
WHERE copado__Status__c IN ('In Progress', 'QA Ready', 'In QA')
AND copado__Pipeline__r.Name = :pipelineName
ORDER BY LastModifiedDate DESC

This retrieves user stories with their recent promotion history in a single API call.

GitHub Actions Integration

The primary use case for the CLI in CI is a daily health check that posts a summary to Slack or fails a scheduled workflow if the pipeline health falls below a threshold:

name: Pipeline health check
on:
  schedule:
    - cron: '0 9 * * 1-5'  # weekdays at 9am

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Install inspector
        run: npm install -g copado-pipeline-inspector

      - name: Auth
        run: |
          copado-inspect auth \
            --instance ${{ secrets.SF_INSTANCE_URL }} \
            --client-id ${{ secrets.SF_CLIENT_ID }} \
            --client-secret ${{ secrets.SF_CLIENT_SECRET }} \
            --username ${{ secrets.SF_USERNAME }} \
            --password ${{ secrets.SF_PASSWORD }}

      - name: Check pipeline health
        run: |
          copado-inspect pipeline \
            --name "Commerce Cloud" \
            --days 7 \
            --fail-below-success-rate 70

If the 7-day success rate drops below 70%, the workflow fails and the team gets notified.

Why This Exists

Copado is expensive. If you’re paying for enterprise Copado licences, you should be using it effectively. The most common failure mode I see is teams that have Copado configured but no visibility into whether it’s actually working well - promotions pile up, blocked stories stay blocked, and nobody notices until a sprint review surfaces a delivery miss.

The inspector makes the pipeline’s health legible without requiring someone to manually pull SOQL queries in Developer Console.

The project is on GitHub.

← All posts