Skip to main content

Check out Port for yourself ➜ 

Gain visibility into delivery performance

Measuring delivery performance is essential for understanding how effectively your engineering teams ship value to customers. Without visibility into delivery metrics, teams struggle to identify bottlenecks, optimize workflows, and make data-driven decisions about process improvements.

This guide helps engineering managers, platform engineers, DevEx teams, and product leaders answer critical questions about their delivery pipeline:

  • Flow: How smoothly does work move through the development lifecycle?
  • Bottlenecks: Where are the friction points that slow down delivery?
  • Predictability: Can we reliably forecast when features will be delivered?

By the end of this guide, you will have a working dashboard that tracks key delivery performance metrics, enabling you to identify improvement opportunities, measure the impact of process changes, and communicate delivery health across your organization.

AI-powered insights

This guide includes configuration for a Delivery Performance Agent that provides AI-powered insights into your delivery flow. Ask natural language questions like "What needs attention right now?" or "What are the top 3 actions we should take to improve PR throughput?" and receive prioritized, actionable recommendations with expected impact and implementation complexity.

Common use cases​

  • Track PR cycle time to identify bottlenecks in reviews and CI processes.
  • Monitor PR throughput to understand delivery flow and detect platform issues.
  • Measure deployment frequency to see how often customer value is shipped.
  • Identify overdue PRs to surface workflow inefficiencies and blocked work.

Prerequisites​

This guide assumes the following:

Initial scope

This guide focuses on measuring delivery performance using source control management (SCM) data, including repositories, pull requests, commits, and workflows. This guide supports GitHub and Azure DevOps, with GitLab support coming soon. This is the first iteration of delivery performance measurement and will expand in future versions to include additional metrics and data sources such as issue trackers, deployment platforms, and other development tools.

Key metrics overview​

We will track four key metrics to measure delivery performance:

MetricWhat it measuresWhy it matters
PR cycle timeTime from PR creation to mergeExposes friction in reviews, CI wait times, and other bottlenecks that slow down delivery
PR throughputNumber of PRs merged over timeShows delivery flow and whether CI or platform issues block output
Deployment frequencyHow often code is deployed to productionShows how often customer value is shipped and indicates delivery cadence
Overdue PRs (open > 3 days)PRs that have been open longer than 3 daysSignals workflow inefficiencies, unclear ownership, or blocked work that needs attention

Set up data model​

We will create several blueprints to model your data. The service blueprint should already exist from onboarding.

Create the GitHub user blueprint

  1. Go to the Builder page of your portal.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose Edit JSON.

  4. Add this JSON schema:

    GitHub user blueprint (click to expand)
    {
      "identifier": "githubUser",
      "title": "Github User",
      "icon": "Github",
      "schema": {
        "properties": {
          "email": {
            "title": "Email",
            "type": "string"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {}
    }

  5. Click Save to create the blueprint.

Create the GitHub repository blueprint

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose Edit JSON.

  4. Add this JSON schema:

    GitHub repository blueprint (click to expand)
    {
      "identifier": "githubRepository",
      "title": "Repository",
      "icon": "Github",
      "ownership": {
        "type": "Direct"
      },
      "schema": {
        "properties": {
          "readme": {
            "title": "README",
            "type": "string",
            "format": "markdown"
          },
          "url": {
            "icon": "DefaultProperty",
            "title": "Repository URL",
            "type": "string",
            "format": "url"
          },
          "defaultBranch": {
            "title": "Default branch",
            "type": "string"
          },
          "last_push": {
            "icon": "GitPullRequest",
            "title": "Last push",
            "description": "Last commit to the main branch",
            "type": "string",
            "format": "date-time"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {
        "service": {
          "title": "Service",
          "target": "service",
          "required": false,
          "many": false
        }
      }
    }

  5. Click Save to create the blueprint.

Create or update the GitHub pull request blueprint

If you already have a pull request blueprint, you need to add the following properties to it. Otherwise, create a new one.

  1. Go to your Builder page.

  2. If you have an existing pull request blueprint, hover over it, click on the ... button, and select Edit JSON. Otherwise, click on + Blueprint and then Edit JSON.

  3. Add or update the JSON schema:

    GitHub pull request blueprint (click to expand)
    {
      "identifier": "githubPullRequest",
      "title": "Pull Request",
      "icon": "Github",
      "schema": {
        "properties": {
          "status": {
            "title": "Status",
            "type": "string",
            "enum": [
              "merged",
              "open",
              "closed"
            ],
            "enumColors": {
              "merged": "purple",
              "open": "green",
              "closed": "red"
            }
          },
          "closedAt": {
            "title": "Closed at",
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "title": "Updated at",
            "type": "string",
            "format": "date-time"
          },
          "mergedAt": {
            "title": "Merged at",
            "type": "string",
            "format": "date-time"
          },
          "createdAt": {
            "title": "Created at",
            "type": "string",
            "format": "date-time"
          },
          "link": {
            "format": "url",
            "type": "string",
            "title": "Link"
          },
          "leadTimeHours": {
            "type": "number",
            "title": "Lead Time Hours"
          },
          "pr_age": {
            "icon": "DefaultProperty",
            "type": "number",
            "title": "PR Age"
          },
          "cycle_time": {
            "type": "number",
            "title": "Cycle Time"
          },
          "pr_age_label": {
            "icon": "DefaultProperty",
            "type": "string",
            "title": "PR Age Label"
          }
        },
        "required": []
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {
          "failedWorkflowsCount": {
            "title": "Failed Workflows",
            "type": "number",
            "description": "Count of failed workflow runs for this PR",
            "target": "githubWorkflowRun",
            "query": {
              "combinator": "and",
              "rules": [
                {
                  "property": "conclusion",
                  "operator": "=",
                  "value": "failure"
                }
              ]
            },
            "calculationSpec": {
              "func": "count",
              "calculationBy": "entities"
            }
          }
      },
      "relations": {
        "git_hub_assignees": {
          "title": "GitHub Assignees",
          "target": "githubUser",
          "required": false,
          "many": true
        },
        "git_hub_creator": {
          "title": "GitHub Creator",
          "target": "githubUser",
          "required": false,
          "many": false
        },
        "repository": {
          "title": "Repository",
          "target": "githubRepository",
          "required": false,
          "many": false
        },
        "git_hub_reviewers": {
          "title": "GitHub Reviewers",
          "target": "githubUser",
          "required": false,
          "many": true
        }
      }
    }
    Properties to create for existing PR blueprint

    If you're updating an existing pull request blueprint, make sure to add the pr_age, cycle_time, and pr_age_label properties if they don't already exist.

  4. Click Save to create or update the blueprint.

Create the deployment blueprint

  1. Go to your Builder page.

  2. Click on + Blueprint.

  3. Click on the {...} button in the top right corner, and choose Edit JSON.

  4. Add this JSON schema:

    Deployment blueprint (click to expand)
    {
      "identifier": "deployment",
      "title": "Deployment",
      "icon": "Deployment",
      "schema": {
        "properties": {
          "description": {
            "title": "Description",
            "type": "string"
          },
          "ref": {
            "title": "Ref",
            "type": "string"
          },
          "sha": {
            "title": "Sha",
            "type": "string"
          },
          "transientEnvironment": {
            "title": "Transient Running Service",
            "type": "boolean"
          },
          "productionEnvironment": {
            "title": "Production Running Service",
            "type": "boolean"
          },
          "createdAt": {
            "title": "Created At",
            "type": "string",
            "format": "date-time"
          },
          "url": {
            "title": "URL",
            "type": "string",
            "icon": "Link",
            "format": "url"
          }
        },
        "required": []
      },
      "mirrorProperties": {
        "owning_team": {
          "title": "Owning Team",
          "path": "service.$team"
        }
      },
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {
        "service": {
          "title": "Service",
          "target": "service",
          "required": false,
          "many": false
        }
      }
    }

  5. Click Save to create the blueprint.

Update integration mapping​

Now we'll configure the GitHub integration to ingest data into your catalog.

  1. Go to your Data Source page.

  2. Select the GitHub integration.

  3. Add the following YAML block into the editor to ingest data from GitHub:

    GitHub integration configuration (click to expand)
    resources:
      - kind: repository
        selector:
          query: 'true'
          teams: true
        port:
          entity:
            mappings:
              identifier: .full_name
              title: .name
              blueprint: '"githubRepository"'
              properties:
                readme: file://README.md
                url: .html_url
                defaultBranch: .default_branch
                last_push: .pushed_at
      - kind: user
        selector:
          query: 'true'
        port:
          entity:
            mappings:
              identifier: .login
              title: .login
              blueprint: '"githubUser"'
      - kind: pull-request
        selector:
          query: 'true'
          closedPullRequests: true
        port:
          entity:
            mappings:
              identifier: .id|tostring
              title: .title
              blueprint: '"githubPullRequest"'
              properties:
                status: .status
                closedAt: .closed_at
                updatedAt: .updated_at
                mergedAt: .merged_at
                createdAt: .created_at
                link: .html_url
                leadTimeHours: >-
                  (.created_at as $createdAt | .merged_at as $mergedAt | ($createdAt
                  | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime)
                  as $createdTimestamp | ($mergedAt | if . == null then null else
                  sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end)
                  as $mergedTimestamp | if $mergedTimestamp == null then null else
                  (((($mergedTimestamp - $createdTimestamp) / 3600) * 100 | floor) /
                  100) end)
                pr_age: >-
                  ((now - (.created_at | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601))
                  / 86400) | round
                pr_age_label: >-
                  ((now - (.created_at | sub("\\.[0-9]+Z$"; "Z") | fromdateiso8601))
                  / 86400 | round) as $age | if $age <= 3 then "0-3 days" elif $age
                  <= 7 then "3-7 days" else ">7 days" end
                cycle_time: >-
                  if .merged_at then (((.merged_at   | sub("\\.[0-9]+Z$"; "Z") |
                  fromdateiso8601) - (.created_at | sub("\\.[0-9]+Z$"; "Z") |
                  fromdateiso8601)) / 86400 | round) else null end
              relations:
                repository: .head.repo.full_name
      - kind: pull-request
        selector:
          query: 'true'
        port:
          entity:
            mappings:
              identifier: .id|tostring
              blueprint: '"githubPullRequest"'
              properties: {}
              relations:
                git_hub_assignees: '[.assignees[].login]'
                git_hub_reviewers: '[.requested_reviewers[].login]'
                git_hub_creator: .user.login
      - kind: deployment
        selector:
          query: 'true'
        port:
          entity:
            mappings:
              identifier: .repo + '-' + (.id|tostring)
              title: .task + '-' + .environment
              blueprint: '"deployment"'
              properties:
                description: .description
                ref: .ref
                sha: .sha
                productionEnvironment: .production_environment
                transientEnvironment: .transient_environment
                createdAt: .created_at
                url: .repository_url
              relations:
                service: .repo

  4. Click Save & Resync to apply the mapping.

Configure AI agent​

To help Platform Engineering teams understand and improve software delivery flow using engineering signals stored in Port's Context Lake, we'll configure an AI agent that provides data-driven insights and actionable recommendations.

  1. Go to the AI Agents page of your portal.

  2. Click on + AI Agent.

  3. Toggle Json mode on.

  4. Copy and paste the following JSON configuration:

    Delivery Performance Agent configuration (click to expand)
    {
      "identifier": "delivery_performance_agent",
      "title": "Delivery Performance Agent",
      "icon": "Details",
      "team": [],
      "properties": {
        "status": "active",
        "tools": [
          "^(list|get|search|track|describe)_.*"
        ],
        "prompt": "You're the Delivery Performance Agent.\nYour purpose is to help Platform Engineering understand and improve software delivery flow using engineering signals stored in Port's Context Lake. You provide accurate, data-driven insights and actionable recommendations that make flow improvements visible, prioritised, and easy to act on.\nAvailable Data\nUse any relevant blueprints and properties available in the Context Lake (for example: Pull Requests, Repositories, Domains, Services, Workflow Runs, Deployments, Teams, or future signals).\n Do not assume a fixed schema. Use only available data.\nYour Task\nInterpret the user's question and determine the appropriate scope (single metric, comparison, trend, ranking, root cause, or systemic pattern).\n\n\nRetrieve and analyse relevant flow signals, such as:\n\n\nLead time, cycle time, throughput\n\n\nReview wait time, PR aging, stalled or stale PRs\n\n\nWorkflow stability and CI reliability\n\n\nVolume and trend changes over time\n\n\nProvide clear, concise insights that directly answer the question.\n\n\nWhen improvement opportunities exist, include recommendations in a structured table.\n\n\nHow to Think\nStay objective and data-based.\n\n\nPrefer organisational and structural patterns over individual examples.\n\n\nAdapt depth to the scope (team, domain, service, or organisation).\n\n\nAvoid speculation; rely only on available signals.\n\n\nIf the question is unclear, ask one targeted follow-up.\n\n\nOutput Format (only top 10 findings)\nDirect Answer\nShort, precise response to the question.\nSupporting Insights\nKey data patterns or trends explaining the outcome.\nRecommendations (Table)\nInclude when relevant:\nRecommendation\nPriority\nExpected Impact\nImplementation Complexity\nRelated Entities\nActionable improvement\nHigh / Medium / Low\nImpact on flow, speed, or predictability\nLow / Medium / High\nURLs to relevant entities if available (otherwise N/A)\n\nRelevant Port Guides (Optional)\nWhen applicable, reference one or more Port guides that help implement the recommendation (for example: scorecards, dashboards, automation, or data model setup).\nInclude only guides that are directly actionable; if none are relevant, omit this section.\nBe concise, accurate, and aligned with Engineering Intelligence principles: flow, visibility, platform foundations, and actionable clarity.\n",
        "execution_mode": "Automatic",
        "conversation_starters": [
          "What needs attention right now?",
          "What are the top 3 actions we should take to improve PR throughput?",
          "Which three top issues should we resolve for the quickest wins to improve delivery speed?",
          "What best practices are top-performing teams using to improve software delivery?"
        ],
        "model": ""
      },
      "relations": {}
    }

  5. Click on Create to save the agent.

MCP Enhanced Capabilities

The AI agent uses MCP (Model Context Protocol) enhanced capabilities to automatically discover important and relevant blueprint entities via its tools. The ^(list|get|search|track|describe)_.* pattern allows the agent to access and analyze related entities in your software catalog, providing richer contextual understanding for agent reasoning and execution.

Visualize metrics​

Once the data is synced, we can create a dedicated dashboard in Port to monitor and analyze delivery performance using customizable widgets.

Create a dashboard​

  1. Navigate to your software catalog.
  2. Click on the + New button in the left sidebar.
  3. Select New dashboard.
  4. Name the dashboard Delivery Performance.
  5. Click Create.

We now have a blank dashboard where we can start adding widgets to visualize delivery performance metrics.

Add widgets​

In the new dashboard, create the following widgets:

Delivery Performance Agent (click to expand)
  1. Click + Widget and select AI Agent.
  2. Title: Delivery Performance Agent.
  3. Choose the Delivery Performance Agent we created earlier.
  4. Click Save.
PR throughput (weekly avg) (click to expand)

  1. Click + Widget and select Number Chart.

  2. Title: PR Throughput (Weekly Avg).

  3. Description: Average pull requests merged in the past 30 days.

  4. Select Count entities Chart type and choose Pull Request as the Blueprint.

  5. Select average for the Function.

  6. Select week for Average of.

  7. Select createdAt for Measure time by.

  8. Add this JSON to the Dataset filter editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "merged",
          "property": "status",
          "operator": "="
        },
        {
          "property": "updatedAt",
          "operator": "between",
          "value": {
            "preset": "lastMonth"
          }
        }
      ]
    }

  9. Select custom as the Unit and input prs as the Custom unit.

  10. Click Save.

PR throughput (weekly trend) (click to expand)

  1. Click + Widget and select Line Chart.

  2. Title: PR Throughput (Weekly Trend).

  3. Select Count Entities (All Entities) Chart type and choose Pull Request as the Blueprint.

  4. Input PR merged as the Y axis Title.

  5. Select count for the Function.

  6. Add this JSON to the Additional filters editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "merged",
          "property": "status",
          "operator": "="
        }
      ]
    }

  7. Input Date as the X axis Title.

  8. Select createdAt for Measure time by.

  9. Set Time Interval to week and Time Range to In the past 30 days.

  10. Click Save.

PR cycle time (weekly avg) (click to expand)

  1. Click + Widget and select Number Chart.

  2. Title: PR Cycle Time (Weekly Avg).

  3. Select Aggregate Property (All Entities) Chart type and choose Pull Request as the Blueprint.

  4. Select cycle_time as the Property.

  5. Select average for the Function.

  6. Select week for Average of.

  7. Select createdAt for Measure time by.

  8. Add this JSON to the Additional filters editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "merged",
          "property": "status",
          "operator": "="
        },
        {
          "property": "updatedAt",
          "operator": "between",
          "value": {
            "preset": "lastMonth"
          }
        }
      ]
    }

  9. Select custom as the Unit and input days as the Custom unit.

  10. Click Save.

PR cycle time (weekly trend) (click to expand)

  1. Click + Widget and select Line Chart.

  2. Title: PR Cycle Time (Weekly Trend).

  3. Select Aggregate Property (All Entities) Chart type and choose Pull Request as the Blueprint.

  4. Input Cycle Time (days) as the Y axis Title.

  5. Select cycle_time as the Property.

  6. Select average for the Function.

  7. Input Date as the X axis Title.

  8. Select createdAt for Measure time by.

  9. Set Time Interval to week and Time Range to In the past 30 days.

  10. Add this JSON to the Additional filters editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "merged",
          "property": "status",
          "operator": "="
        }
      ]
    }

  11. Click Save.

Deployment frequency (click to expand)
  1. Click + Widget and select Number Chart.
  2. Title: Deployment Frequency.
  3. Select Count entities Chart type and choose Deployment as the Blueprint.
  4. Select count for the Function.
  5. Select custom as the Unit and input deployments as the Custom unit.
  6. Click Save.
Deployment frequency (weekly trend) (click to expand)
  1. Click + Widget and select Line Chart.
  2. Title: Deployment Frequency (Weekly Trend).
  3. Select Count Entities (All Entities) Chart type and choose Deployment as the Blueprint.
  4. Input Deployments as the Y axis Title.
  5. Select count for the Function.
  6. Input Date as the X axis Title.
  7. Select createdAt for Measure time by.
  8. Set Time Interval to week and Time Range to In the past 30 days.
  9. Click Save.
Overdue PRs (click to expand)

  1. Click + Widget and select Number Chart.

  2. Title: Overdue PRs.

  3. Description: PRs opened longer than 3 days.

  4. Select Count entities Chart type and choose Pull Request as the Blueprint.

  5. Select count for the Function.

  6. Add this JSON to the Dataset filter editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "open",
          "property": "status",
          "operator": "="
        },
        {
          "value": 3,
          "property": "pr_age",
          "operator": ">"
        },
        {
          "property": "createdAt",
          "operator": "between",
          "value": {
            "preset": "lastMonth"
          }
        }
      ]
    }

  7. Select custom as the Unit and input prs as the Custom unit.

  8. Click Save.

PR age distribution (click to expand)

  1. Click + Widget and select Pie chart.

  2. Title: PR Age Distribution.

  3. Description: 0–3 days | 3–7 days | >7 days.

  4. Choose the Pull Request blueprint.

  5. Under Breakdown by property, select the PR Age property.

  6. Add this JSON to the Additional filters editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "open",
          "property": "status",
          "operator": "="
        },
        {
          "property": "createdAt",
          "operator": "between",
          "value": {
            "preset": "lastMonth"
          }
        }
      ]
    }

  7. Click Save.

Overdue PRs table (click to expand)

  1. Click + Widget and select Table.

  2. Title the widget Overdue PRs.

  3. Choose the Pull Request blueprint.

  4. Add this JSON to the Initial filters editor:

    {
      "combinator": "and",
      "rules": [
        {
          "value": "open",
          "property": "status",
          "operator": "="
        },
        {
          "value": 3,
          "property": "pr_age",
          "operator": ">"
        },
        {
          "property": "createdAt",
          "operator": "between",
          "value": {
            "preset": "lastMonth"
          }
        }
      ]
    }

  5. Click Save to add the widget to the dashboard.

  6. Click on the ... button in the top right corner of the table and select Customize table.

  7. In the top right corner of the table, click on Manage Properties and add the following properties:

    • Repository: The name of each related repository.
    • Link: The URL to the pull request.
    • Title: The title of the pull request.
    • Owning Team: The team that owns the service (via repository relation).
    • PR Age: The age of the pull request in days.

  8. Click on the save icon in the top right corner of the widget to save the customized table.

Last updated on