> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Visualize and manage Git deployments

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

This guide demonstrates how to ingest, visualize, and manage GitHub and GitLab deployments in Port.

You will:

  • Ingest GitHub workflow runs or GitLab pipelines into Port's context lake.
  • Create self-service actions to trigger, retry, and cancel deployments.
  • Build a dashboard to monitor deployments and run actions.
GitHub deployment manager dashboard overviewGitHub deployments table with re-run and cancel actions

Common use cases

  • Monitor deployment status and health across repositories from one dashboard.
  • Let platform teams run deployment operations through governed self-service actions.

Prerequisites

Set up data model

The deployment blueprints are not created automatically when you install the GitHub or GitLab integration. Create the blueprints for your provider before updating its mapping.

Create the GitHub workflow blueprint

  1. Go to the Data model page in Port.

  2. Click on + Blueprint.

  3. Click on Edit JSON.

  4. Copy and paste the following JSON configuration into the editor:

    GitHub workflow blueprint (click to expand)
    {
    "identifier": "githubWorkflow",
    "title": "Workflow",
    "icon": "Github",
    "schema": {
    "properties": {
    "path": {
    "title": "Path",
    "type": "string"
    },
    "status": {
    "title": "Status",
    "type": "string",
    "enum": [
    "active",
    "deleted",
    "disabled_fork",
    "disabled_inactivity",
    "disabled_manually"
    ],
    "enumColors": {
    "active": "green",
    "deleted": "red"
    }
    },
    "createdAt": {
    "title": "Created at",
    "type": "string",
    "format": "date-time"
    },
    "updatedAt": {
    "title": "Updated at",
    "type": "string",
    "format": "date-time"
    },
    "deletedAt": {
    "title": "Deleted at",
    "type": "string",
    "format": "date-time"
    },
    "link": {
    "title": "Link",
    "type": "string",
    "format": "url"
    }
    },
    "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "relations": {
    "repository": {
    "title": "Repository",
    "target": "service",
    "required": false,
    "many": false
    }
    }
    }
  5. Click Save to create the blueprint.

Create the GitHub workflow run blueprint

  1. Go to the Data model page in Port.

  2. Click on + Blueprint.

  3. Click on Edit JSON.

  4. Copy and paste the following JSON configuration into the editor:

    GitHub workflow run blueprint (click to expand)
    {
    "identifier": "githubWorkflowRun",
    "title": "Workflow Run",
    "icon": "Github",
    "schema": {
    "properties": {
    "name": {
    "title": "Name",
    "type": "string"
    },
    "triggeringActor": {
    "title": "Triggering actor",
    "type": "string"
    },
    "status": {
    "title": "Status",
    "type": "string",
    "enum": [
    "completed",
    "action_required",
    "cancelled",
    "startup_failure",
    "failure",
    "neutral",
    "skipped",
    "stale",
    "success",
    "timed_out",
    "in_progress",
    "queued",
    "requested",
    "waiting"
    ],
    "enumColors": {
    "queued": "yellow",
    "in_progress": "yellow",
    "success": "green",
    "failure": "red"
    }
    },
    "conclusion": {
    "title": "Conclusion",
    "type": "string",
    "enum": [
    "completed",
    "action_required",
    "cancelled",
    "startup_failure",
    "failure",
    "neutral",
    "skipped",
    "stale",
    "success",
    "timed_out",
    "in_progress",
    "queued",
    "requested",
    "waiting"
    ],
    "enumColors": {
    "queued": "yellow",
    "in_progress": "yellow",
    "success": "green",
    "failure": "red"
    }
    },
    "createdAt": {
    "title": "Created at",
    "type": "string",
    "format": "date-time"
    },
    "runStartedAt": {
    "title": "Run started at",
    "type": "string",
    "format": "date-time"
    },
    "updatedAt": {
    "title": "Updated at",
    "type": "string",
    "format": "date-time"
    },
    "runNumber": {
    "title": "Run number",
    "type": "number"
    },
    "runAttempt": {
    "title": "Run attempts",
    "type": "number"
    },
    "link": {
    "title": "Link",
    "type": "string",
    "format": "url"
    }
    },
    "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "relations": {
    "workflow": {
    "target": "githubWorkflow",
    "required": true,
    "many": false
    }
    }
    }
  5. Click Save to create the blueprint.

Update integration mapping

Configure your provider integration to ingest the deployment entities represented by the blueprints.

Update GitHub mapping

  1. In your GitHub repository, create or update port-app-config.yml.

  2. Add the following configuration to ingest repositories, workflows, and workflow runs:

    GitHub integration configuration (click to expand)
    resources:
    - kind: repository
    selector:
    query: "true"
    includedFiles:
    - README.md
    port:
    entity:
    mappings:
    identifier: .name
    title: .name
    blueprint: '"service"'
    properties:
    readme: .__includedFiles["README.md"]
    url: .html_url
    defaultBranch: .default_branch
    - kind: workflow
    selector:
    query: "true"
    port:
    entity:
    mappings:
    identifier: ".__repository + (.id | tostring)"
    title: .name
    blueprint: '"githubWorkflow"'
    properties:
    path: .path
    status: .state
    createdAt: .created_at
    updatedAt: .updated_at
    link: .html_url
    relations:
    repository: ".__repository"
    - kind: workflow-run
    selector:
    query: "true"
    port:
    entity:
    mappings:
    identifier: ".repository.name + \"/\" + (.id | tostring)"
    title: .display_title
    blueprint: '"githubWorkflowRun"'
    properties:
    name: .name
    triggeringActor: .triggering_actor.login
    status: .status
    conclusion: .conclusion
    createdAt: .created_at
    runStartedAt: .run_started_at
    updatedAt: .updated_at
    runNumber: .run_number
    runAttempt: .run_attempt
    link: .html_url
    relations:
    workflow: ".repository.name + (.workflow_id | tostring)"
  3. Commit and push port-app-config.yml. The GitHub integration will sync the workflows and workflow runs automatically.

Set up self-service actions

Create three synced-webhook actions for your provider: trigger a deployment, retry a failed deployment, and cancel a running deployment.

Add Port secret

Add a GitHub token that Port can use to call the GitHub Actions API:

  1. Open the Credentials modal.

  2. Click on the Secrets tab.

  3. Click on + Secret and add _GITHUB_TOKEN. Use a fine-grained personal access token with Actions: Read and write repository permission.

Set up self-service action

This action starts the selected GitHub workflow on the main branch and passes the chosen environment as a workflow input.

  1. Go to the Self-service page in Port.

  2. Click on the + New Action button.

  3. Click on the {...} Edit JSON button.

  4. Copy and paste the following JSON configuration into the editor:

    Trigger a GitHub workflow run (click to expand)
    Replace the GitHub organization

    Replace <YOUR_GITHUB_ORG> in the webhook URL with your GitHub organization name.

    {
    "identifier": "trigger_workflow_run",
    "title": "Trigger workflow run",
    "icon": "Github",
    "description": "Trigger a GitHub workflow run in the selected repository",
    "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
    "properties": {
    "environment": {
    "icon": "DefaultProperty",
    "title": "Environment",
    "type": "string",
    "default": "test",
    "enum": [
    "test",
    "staging",
    "production"
    ],
    "enumColors": {
    "test": "lightGray",
    "staging": "lightGray",
    "production": "lightGray"
    }
    }
    },
    "required": [],
    "order": [
    "environment"
    ]
    },
    "blueprintIdentifier": "githubWorkflow"
    },
    "invocationMethod": {
    "type": "WEBHOOK",
    "url": "https://api.github.com/repos/<YOUR_GITHUB_ORG>/{{ .entity.relations.repository }}/actions/workflows/{{ .entity.properties.path | split(\"/\")[-1] }}/dispatches",
    "agent": false,
    "synchronized": true,
    "method": "POST",
    "headers": {
    "Accept": "application/vnd.github+json",
    "Authorization": "Bearer {{ .secrets._GITHUB_TOKEN }}",
    "X-GitHub-Api-Version": "2022-11-28",
    "Content-Type": "application/json"
    },
    "body": {
    "ref": "main",
    "inputs": {
    "environment": "{{ .inputs.environment }}"
    }
    }
    },
    "requiredApproval": false
    }
  5. Click Save to create the action.

The Trigger workflow run action now appears for entities based on the GitHub Workflow blueprint.

Visualize deployments

With deployment entities ingested and actions configured, create a dashboard to monitor deployment health and run remediation actions.

Create the GitHub dashboard

  1. Navigate to your context lake.

  2. Click on the + button in the left sidebar.

  3. Select New dashboard.

  4. Name the dashboard GitHub Deployment Manager.

  5. Enter A dashboard to view, re-run, and cancel deployments in GitHub under Description.

  6. Select the Github icon.

  7. Click Create.

The dashboard is now ready for widgets that visualize GitHub workflow runs and expose the deployment actions.

Choose your deployment filter

This guide treats workflow runs as deployments when their titles contain deploy, CD, production, or staging. Adjust these filters to match your workflow naming conventions.

You can instead ingest GitHub's native deployment objects by mapping the deployment resource kind. See the GitHub deployment mapping example.

Add GitHub widgets

Add the following widgets to the dashboard:

Total deployments created in the last three months (click to expand)
  1. Click + Widget and select Number chart.

  2. Enter Total deployments under Title and select the Deployment icon.

  3. Select Count entities as the Chart type and GitHub Workflow Run as the Blueprint.

  4. Select count under Function.

  5. Add the following JSON to the Additional filters editor:

    [
    {
    "combinator": "and",
    "rules": [
    {
    "property": "$title",
    "operator": "contains",
    "value": "deploy"
    },
    {
    "property": "createdAt",
    "operator": "between",
    "value": {
    "preset": "last3Months"
    }
    }
    ]
    }
    ]
  6. Select custom as the Unit and enter deployments as the Custom unit.

  7. Click Save.

Deployments by status (click to expand)
  1. Click + Widget and select Pie chart.

  2. Enter Deployments by status under Title and select the Deployment icon.

  3. Select GitHub Workflow Run as the Blueprint.

  4. Select Conclusion under Breakdown by property.

  5. Add the following JSON to the Additional filters editor:

    {
    "combinator": "or",
    "rules": [
    {
    "property": "$title",
    "operator": "contains",
    "value": "deploy"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "production"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "CD"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "staging"
    }
    ]
    }
  6. Click Save.

Trigger workflow run action (click to expand)
  1. Click + Widget and select Action card.

  2. Select the Trigger workflow run action.

  3. Click Save.

All GitHub deployments (click to expand)
  1. Click + Widget and select Table.

  2. Enter All deployments under Title.

  3. Select GitHub Workflow Run as the Blueprint.

  4. Add the following JSON to the Additional filters editor:

    {
    "combinator": "or",
    "rules": [
    {
    "property": "$title",
    "operator": "contains",
    "value": "deploy"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "production"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "CD"
    },
    {
    "property": "$title",
    "operator": "contains",
    "value": "staging"
    }
    ]
    }
  5. Click Save to add the widget.

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

  7. Click Manage properties and add:

    • Conclusion - The conclusion of the workflow run.
    • Link - The URL of the workflow run.
    • Created at - The date when GitHub created the workflow run.
    • Run number - The workflow run number.
    • Run attempts - The number of attempts for the workflow run.
  8. Click the save icon to save the customized table.

Let's test it!

  1. Open the GitHub Deployment Manager dashboard.

  2. Confirm that recent deployment workflow runs appear in the widgets.

  3. Run the Trigger workflow run action and confirm that GitHub starts the workflow.

  4. Open an eligible workflow run and test the Re-run workflow run or Cancel workflow run action.

  5. Resync the GitHub integration and confirm that Port reflects the updated workflow run status.