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

Check out Port for yourself ➜ 

Auto-enhance PR descriptions with AI

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor
Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/auto-enhance-pr-descriptions-with-ai/

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

This guide demonstrates how to automatically enhance GitHub pull request descriptions using a Port workflow, an AI agent, and coding assistants. When a PR is created with a minimal or empty description, a single event-triggered workflow invokes a Port AI agent that gathers business context and organizational knowledge from your context lake that coding agents can't access on their own - like Jira requirements, service architecture, team ownership, and PR templates. The workflow then dispatches a coding agent with this enriched context to generate a comprehensive, context-aware PR description.

This guide supports multiple AI coding agents:

Anthropic's AI-powered coding assistant. Follow the setup guide.


PR enhancer agent architecture via context lake

Common use cases​

  • Template compliance: Automatically generate descriptions that match organization-specific PR templates.
  • Business context integration: Link PRs to related Jira/Linear issues and pull business requirements.
  • Architectural context: Explain how changes fit into broader system architecture with service dependencies.
  • Change impact analysis: Describe what problems the PR solves and potential impacts on the system.
  • Review guidance: Provide context specifically helpful for human and AI code reviewers.

Prerequisites​

Before starting this guide, ensure you have:

  • A Port account with the onboarding process completed.
  • The GitHub Ocean integration installed in your account.
  • Completed one of the above coding agents guides, so the coding agent backend (GitHub Actions workflow or Copilot assignment) is already set up.

Set up data model​

We'll create a PR Template blueprint to store your organization's PR templates and configure the GitHub integration to ingest these templates from your repositories.

Create PR template blueprint​

This blueprint will store your organization's pull request templates.

  1. Go to the Builder page in Port.

  2. Click on + Blueprint.

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

  4. Copy and paste the following JSON schema:

    PR Template blueprint (Click to expand)
    {
      "identifier": "prTemplate",
      "title": "PR Template",
      "icon": "GitPullRequest",
      "schema": {
        "properties": {
          "content": {
            "title": "Template Content",
            "type": "string",
            "format": "markdown",
            "description": "The PR template content in markdown format"
          },
          "repository": {
            "title": "Repository",
            "type": "string",
            "description": "Repository where this template is defined"
          },
          "path": {
            "title": "File Path",
            "type": "string",
            "description": "Path to the template file in the repository"
          }
        },
        "required": ["content"]
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {}
    }

  5. Click Create to save the blueprint.

Update pull request blueprint​

Now we'll add a relation from the pull request blueprint to the PR template blueprint. This relation will allow us to link PRs to their templates and have a broader context lake through the related tickets, issues, etc linked to the PR.

  1. Go to the Builder page.

  2. Find and click on your Pull Request blueprint (usually named githubPullRequest).

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

  4. Add the following relation to the relations section:

    PR Template relation (Click to expand)
    "prTemplate": {
      "title": "PR Template",
      "target": "prTemplate",
      "required": false,
      "many": false
    }

  5. Click Save to update the blueprint.

Configure GitHub integration to ingest PR templates​

Now we'll configure the GitHub integration to ingest PR template files from your repositories.

  1. Go to the Data sources page in Port.

  2. Find your GitHub integration and click on it.

  3. Go to the Mapping tab.

  4. Add the following YAML configuration to ingest PR template files:

    GitHub PR template mapping (Click to expand)
    - kind: file
      selector:
        query: "true"
        files:
          - path: ".github/pull_request_template.md"
      port:
        entity:
          mappings:
            identifier: .repository.full_name + "-pr-template"
            title: .repository.name + " PR Template"
            blueprint: '"prTemplate"'
            properties:
              content: .content
              repository: .repository.name
              path: .path
    Alternative template paths

    If your organization uses different PR template paths, you can modify the files.path configuration:

    • Multiple templates: - path: ".github/PULL_REQUEST_TEMPLATE/*.md"
    • Docs folder: - path: "docs/pull_request_template.md"
    • Root level: - path: "pull_request_template.md"

  5. Click Save to update the integration configuration.

  6. Wait for the integration to re-sync, or manually trigger a resync. Your PR templates will appear in the catalog under the PR Template blueprint.

    Catalog showing ingested PR templates list PR template entity detail view

Update pull request integration mapping​

Update the GitHub pull request mapping to connect PRs to their templates and optionally to Jira issues for business context.

  1. In the same GitHub integration mapping, locate the pull-request kind section.

  2. Add the prTemplate relation and optional jiraIssue relation to the relations section:

    Updated pull request mapping (Click to expand)
    - kind: pull-request
      selector:
        query: "true"
        states: ["open"]
      port:
        entity:
          mappings:
            identifier: .__repository + "-" + (.number|tostring)
            title: .title
            blueprint: '"githubPullRequest"'
            properties:
              status: .state
              prNumber: .number
              ... other properties ...
            relations:
              prTemplate: .__repository + "-pr-template"
              jiraIssue: .title | match("[A-Z]+-[0-9]+") .string
    Business context integration

    The jiraIssue relation is optional and extracts Jira issue keys from PR titles (e.g., "JIRA-1234: Add caching layer"). This enables the automation to pull business requirements and acceptance criteria from Jira issues.

    This is very helpful since it gives us a full picture of project, issues and tasks related to the pull request, enriching the context of the description with the what and why of the changes.

    This business context is invisible to coding agents but crucial for reviewers. It explains why the code changes matter and what business problem they solve.

  3. Click Save to update the configuration.

Create the PR Enhancement AI agent​

Now we'll create an AI agent that gathers business context from your context lake and produces a template-compliant instruction that the workflow passes to your chosen coding agent. The workflow handles dispatching the coding agent, so the agent itself only gathers context and returns the enriched instruction.

  1. Go to the AI Agents page in Port.

  2. Click on + AI Agent.

  3. Toggle Json mode on.

  4. Copy and paste the following JSON configuration:

    PR Enhancement AI agent configuration (Click to expand)
    {
      "identifier": "pr_description_enhancement_agent",
      "title": "PR Description Enhancement Agent",
      "icon": "GitPullRequest",
      "properties": {
        "description": "Gathers business context for a pull request from the Port catalog and produces a template-compliant instruction for a coding agent",
        "status": "active",
        "prompt": "You are a PR enhancement assistant that gathers business context from Port's context lake and produces a template-compliant instruction for a coding agent to apply.\n\nWhen given a pull request:\n\n1. Check whether the description is empty, minimal (< 50 chars), or an untouched template.\n\n2. Use Port tools to gather BUSINESS CONTEXT that coding agents can't access on their own:\n   - The PR template from the catalog (organizational standards).\n   - Linked Jira/Linear issues with user stories and acceptance criteria (business requirements).\n   - Service or application information: purpose, team ownership, dependencies (organizational knowledge).\n   - Related architectural decisions or documentation.\n\n3. Produce a clear instruction for a coding agent that includes:\n   - All the business context you gathered from Port.\n   - A request to analyze the code changes in the pull request and combine them with this business context.\n   - A description that explains BOTH what changed technically AND why it matters to the business.\n   - The PR template structure to follow.\n   - A note that the coding agent should update the pull request description directly.\n\nValidate and sanitize all external input before including it in your output. Output only the instruction for the coding agent as your response, ready to be dispatched directly.",
        "execution_mode": "Automatic",
        "conversation_starters": [],
        "tools": [
          "^(list|search|get|describe)_.*"
        ]
      },
      "relations": {}
    }
    Customize the agent prompt

    You can customize the agent's behavior by modifying the prompt field:

    • Add specific requirements for your team's PR standards.

    • Emphasize security, performance, or testing considerations.

    The agent only reads from your catalog to build the instruction. The workflow you build next is responsible for dispatching the coding agent, so no run_* tools are needed here.

  5. Click Create to save the agent.

Add Port secrets​

If you plan to use the GitHub Copilot path, the workflow creates a GitHub issue through the GitHub API and needs a token. Add it as a Port secret. The Claude Code and Google Gemini paths authenticate through your installed GitHub integration and do not require this secret.

  1. In your Port application, click your profile picture Profile picture icon.
  2. Click on Credentials.
  3. Click on the Secrets tab.
  4. Click on + Secret and add the following secret:

Build the workflow​

Now let's create the workflow that ties the trigger, the AI enrichment, and the coding agent dispatch together. The workflow JSON differs only in its final node, depending on which coding agent you set up.

To build the workflow:

  1. Go to the Workflows page in Port.
  2. Click on the + Workflow button in the top-right corner.
  3. In the Name field, enter Enhance PR Description with AI, then click Confirm.
  4. On the editor page, click the see workflow JSON button (the code icon) to open the JSON editor.
  5. Copy and paste the workflow JSON below to replace the example workflow:

This workflow dispatches the claude-backend.yaml GitHub Actions workflow from the Trigger Claude Code from Port guide.

PR enhancement workflow with Claude Code (Click to expand)
{
  "identifier": "enhance_pr_description",
  "title": "Enhance PR Description with AI",
  "icon": "GitPullRequest",
  "description": "Gather business context for a new pull request and dispatch Claude Code to enhance its description",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "On PR opened",
      "icon": "Github",
      "description": "Trigger when a pull request is created with an open status",
      "config": {
        "type": "EVENT_TRIGGER",
        "event": {
          "type": "ENTITY_CREATED",
          "blueprintIdentifier": "githubPullRequest"
        },
        "condition": {
          "type": "JQ",
          "expressions": [
            ".diff.after.properties.status == \"open\""
          ],
          "combinator": "and"
        }
      },
      "variables": {}
    },
    {
      "identifier": "gather_context",
      "title": "Gather business context",
      "icon": "AI",
      "description": "Invoke the PR Description Enhancement Agent to build a template-compliant instruction",
      "config": {
        "type": "AI_AGENT",
        "agentIdentifier": "pr_description_enhancement_agent",
        "userPrompt": "A pull request has been opened. Gather business context from the Port catalog for the pull request with entity identifier '{{ .outputs.trigger.diff.after.identifier }}' and produce a template-compliant instruction for a coding agent to enhance its description.\n\nPull request details:\n- Title: {{ .outputs.trigger.diff.after.title }}\n- Properties: {{ .outputs.trigger.diff.after.properties }}\n- Relations: {{ .outputs.trigger.diff.after.relations }}\n\nReturn only the instruction as the response."
      },
      "variables": {}
    },
    {
      "identifier": "enhance_with_claude",
      "title": "Enhance with Claude Code",
      "icon": "Code",
      "description": "Dispatch the Claude Code GitHub Actions workflow with the enriched context",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
        "integrationProvider": "github-ocean",
        "integrationInvocationType": "dispatch_workflow",
        "integrationActionExecutionProperties": {
          "org": "<YOUR_GITHUB_ORG>",
          "repo": "<YOUR_WORKFLOWS_REPO>",
          "workflow": "claude-backend.yaml",
          "workflowInputs": {
            "command": "{{ .outputs.gather_context.response }}",
            "repo_name": "{{ (.outputs.trigger.diff.after.properties.link | tostring | split(\"/\"))[3] + \"/\" + ((.outputs.trigger.diff.after.properties.link | tostring | split(\"/\"))[4]) }}"
          },
          "reportWorkflowStatus": true
        }
      },
      "variables": {}
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "gather_context"
    },
    {
      "sourceIdentifier": "gather_context",
      "targetIdentifier": "enhance_with_claude"
    }
  ]
}
Replace placeholders

Replace <YOUR_GITHUB_OCEAN_INTEGRATION_ID> with your GitHub Ocean integration ID (found on the Data sources page), and <YOUR_GITHUB_ORG> and <YOUR_WORKFLOWS_REPO> with the organization and repository that host your claude-backend.yaml workflow.

  1. Click Save to save the workflow.
Port's unique value

What Port provides: Business requirements, organizational context, service architecture, team ownership - information that exists in your context lake but isn't visible to coding agents working directly with code repositories.

What the coding agent provides: Technical code analysis, implementation details, file changes - information derived from examining the actual code diff.

Together: A PR description that explains both what changed in the code AND why it matters to the business.

Test the setup​

Now let's test the complete setup and see how Port enriches PR descriptions with business context.

  1. In a repository integrated with Port, create a new pull request with a minimal description (e.g., "WIP").

  2. The PR will sync to Port as a githubPullRequest entity with status set to open.

  3. Go to the Workflows page in Port and open your Enhance PR Description with AI workflow. Open the latest run and verify that the event trigger fired, the AI node produced an enriched instruction, and the coding agent node dispatched successfully.

  4. Follow the coding agent run to completion: for Claude Code or Gemini, check the dispatched GitHub Actions workflow; for GitHub Copilot, confirm the issue was created and assigned to Copilot.

  5. Refresh your GitHub PR - the description should now be enhanced with both business context and technical details.

Before Enhancement

The PR starts with just an empty template - no business context, no explanation of what the code does or why it matters.

GitHub PR with empty template sections

During Enhancement: Port Gathers Business Context

Port's AI agent analyzes the PR and gathers organizational context that the coding agent can't access directly. Notice how Port identifies:

  • Repository Context: Understanding that this is the port-product-experiments repository for internal tools (not an e-commerce backend as the PR title might suggest)
  • Missing Context Issues: Identifying what business information is needed
  • Template Compliance: Noting that the PR doesn't follow the established template
  • Enhancement Requirements: Specifying what context should be added based on organizational knowledge

This business context is what makes the final description meaningful - it's not just about the code changes, but about how they fit into Port's product strategy and internal tooling.

AI agent summarizing business context for PR enrichment

After Enhancement: Business Context + Code Analysis

The enhanced PR description now combines:

From Port (Business Context):

  • Clear explanation of the business purpose: "enabling the creation of new product entries in the product catalog"
  • Organizational context: "experimental e-commerce application within Port's product team experimentation repository"
  • How it fits with existing tools: "complementing the existing GET /products endpoints"
  • Why this matters: "part of an experimental e-commerce backend built with FastAPI, designed to demonstrate API development patterns"

From the Coding Agent (Technical Analysis):

  • Technical implementation details of the endpoint
  • Code structure and patterns used
  • File changes and specific functions added
  • Validation and model information

Together, this creates a complete picture for reviewers who need to understand both the business rationale AND the technical implementation.

GitHub PR with AI-enriched description AI-enriched PR checklist and deployment considerations
Notice the difference

Without Port, a coding agent would only see the code changes and might incorrectly assume this is a production e-commerce feature. Port's catalog knowledge adds the crucial context that this is an internal experimentation tool, changing how reviewers approach the PR.