Connect GitHub Pull Request with Jira Issue

This guide demonstrates how to connect a GitHub pull request with a Jira issue in Port, enhancing traceability and improving project workflows.

Available Github Integrations

This guide includes steps that require integration with GitHub:

GitHub (Ocean) - uses the Ocean framework. We strongly recommend this integration for new and migrated setups.
GitHub (Sunset) - uses a GitHub app that is in sunset and will be fully deprecated on September 15, 2026.

Prerequisites

This guide assumes you have a Port account and that you have finished the onboarding process.
Install Port's Jira integration.

GitHub (Ocean)
GitHub (Sunset)

Install GitHub ocean.

Set up data model

GitHub (Ocean)
GitHub (Sunset)

We highly recommend you install both GitHub ocean and Jira integration to have pull requests and issues automatically ingested into Port in real-time. However, if you haven't installed GitHub ocean and Jira integration, you'll need to create blueprints for GitHub pull requests and Jira issues in Port. Skip this section if you have already installed GitHub ocean and Jira integration.

Add the pull request blueprint

Go to your Builder page.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Add this JSON schema:

GitHub Pull Request Blueprint (Click to expand)

{
    "identifier": "githubPullRequest",
    "title": "Pull Request",
    "icon": "Github",
    "schema": {
        "properties": {
            "creator": {
                "title": "Creator",
                "type": "string"
            },
            "assignees": {
                "title": "Assignees",
                "type": "array"
            },
            "reviewers": {
                "title": "Reviewers",
                "type": "array"
            },
            "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"
            },
            "link": {
                "type": "string",
                "format": "url"
            }
        },
        "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
}

Click Save to create the blueprint.

Add pull request mapping config

Go to your data sources page, and click on your GitHub ocean integration.

Add the following YAML block into the editor to map the pull request data:

Relation mapping (Click to expand)

resources:
  - kind: pull-request
    selector:
      query: "true"
      states: ["open"]
    port:
      entity:
        mappings:
          identifier: .__repository + "-" + (.number|tostring)
          title: .title
          blueprint: '"githubPullRequest"'
          properties:
            creator: .user.login
            assignees: "[.assignees[].login]"
            reviewers: "[.requested_reviewers[].login]"
            status: .state
            closedAt: .closed_at
            updatedAt: .updated_at
            mergedAt: .merged_at
            prNumber: .number
            link: .html_url
          relations:
            repository: .__repository

Click Save & Resync to apply the mapping.

Great! Now that the mapping is configured, you will need to manually ingest your pull requests data into Port

We highly recommend you install both the GitHub app and Jira integration to have pull requests and issues automatically ingested into Port in real-time. However, if you haven't installed Port's GitHub app and Jira integration, you'll need to create blueprints for GitHub pull requests and Jira issues in Port. Skip this section if you have already installed the GitHub app and Jira integration.

Add the pull request blueprint

Go to your Builder page.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Add this JSON schema:

GitHub Pull Request Blueprint (Click to expand)

{
    "identifier": "githubPullRequest",
    "title": "Pull Request",
    "icon": "Github",
    "schema": {
        "properties": {
            "creator": {
                "title": "Creator",
                "type": "string"
            },
            "assignees": {
                "title": "Assignees",
                "type": "array"
            },
            "reviewers": {
                "title": "Reviewers",
                "type": "array"
            },
            "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"
            },
            "link": {
                "type": "string",
                "format": "url"
            }
        },
        "required": []
    },
    "mirrorProperties": {},
    "calculationProperties": {},
    "aggregationProperties": {},
    "relations": {}
}

Click Save to create the blueprint.

Add pull request mapping config

Go to your data sources page, and select the Github data source:

Add the following YAML block into the editor to map the pull request data:

Relation mapping (Click to expand)

resources:
  - kind: pull-request
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: ".head.repo.name + '-' + (.number|tostring)"
          title: ".title"
          blueprint: '"githubPullRequest"'
          properties:
            creator: ".user.login"
            assignees: "[.assignees[].login]"
            reviewers: "[.requested_reviewers[].login]"
            status: ".status"
            closedAt: ".closed_at"
            updatedAt: ".updated_at"
            mergedAt: ".merged_at"
            prNumber: ".id"
            link: ".html_url"

Click Save & Resync to apply the mapping.

Great! Now that the mapping is configured, you will need to manually ingest your pull requests data into Port

Add Jira issue blueprint

Go to your Builder page.
Click on + Blueprint.
Click on the {...} button in the top right corner, and choose "Edit JSON".

Add this JSON schema:

Jira Issue Blueprint (Click to expand)

{
  "identifier": "jiraIssue",
  "title": "Jira Issue",
  "icon": "Jira",
  "schema": {
    "properties": {
      "url": {
        "title": "Issue URL",
        "type": "string",
        "format": "url",
        "description": "URL to the issue in Jira"
      },
      "status": {
        "title": "Status",
        "type": "string",
        "description": "The status of the issue"
      },
      "issueType": {
        "title": "Type",
        "type": "string",
        "description": "The type of the issue"
      },
      "components": {
        "title": "Components",
        "type": "array",
        "description": "The components related to this issue"
      },
      "assignee": {
        "title": "Assignee",
        "type": "string",
        "format": "user",
        "description": "The user assigned to the issue"
      },
      "reporter": {
        "title": "Reporter",
        "type": "string",
        "description": "The user that reported to the issue",
        "format": "user"
      },
      "creator": {
        "title": "Creator",
        "type": "string",
        "description": "The user that created to the issue",
        "format": "user"
      },
      "priority": {
        "title": "Priority",
        "type": "string",
        "description": "The priority of the issue"
      },
      "created": {
        "title": "Created At",
        "type": "string",
        "description": "The created datetime of the issue",
        "format": "date-time"
      },
      "updated": {
        "title": "Updated At",
        "type": "string",
        "description": "The updated datetime of the issue",
        "format": "date-time"
      }
    }
  },
  "calculationProperties": {},
  "mirrorProperties": {},
  "aggregationProperties": {},
  "relations": {}
}

Click Save to create the blueprint.

Add Jira mapping config

Go to your data sources page, and click on your Jira integration.

Under the resources key, add the following YAML block to map Jira issues:

Jira Issue mapping (Click to expand)

resources:
  - kind: issue
    selector:
      query: "true"
    port:
      entity:
        mappings:
          identifier: .key
          title: .fields.summary
          blueprint: '"jiraIssue"'
          properties:
            url: .self
            status: .fields.status.name
            issueType: .fields.issuetype.name
            components: "[.fields.components[].name]"
            assignee: .fields.assignee.emailAddress
            reporter: .fields.reporter.emailAddress
            creator: .fields.creator.emailAddress
            priority: .fields.priority.name
            created: .fields.created
            updated: .fields.updated

Click Save & Resync to apply the mapping.

Great! Now that the mapping is configured, you will need to manually ingest your Jira issues data into Port

Relate pull requests to Jira issues

Now that Port is synced with our Jira resources, let's map the Jira issues to the Github pull requests.

First, we will need to create a relation between our githubPullRequest and the corresponding jiraIssue.

Head back to the Builder, choose the Pull Request blueprint, and click on New relation:
Fill out the form like this, then click Create:

Now that the blueprints are related, we need to assign the relevant Jira Issue to each of our pull requests.
This can be done by adding some mapping logic, using one of the following methods:

Direct identifier mapping
Search query

The most straightforward way to set a relation's value is to explicitly specify the related entity's identifier.
Follow the steps below to map pull request entities with Jira issues using direct identifier mapping:

Go to your data sources page
Click on your Github integration:

GitHub (Ocean)
GitHub (Sunset)

Under the resources key, find the Pull Request block

Replace it with the following YAML configuration to map pull request entities with Jira issues:

Relation mapping (click to expand)

- kind: pull-request
  selector:
    query: "true"
    states: ["open"]
  port:
    entity:
      mappings:
        identifier: .__repository + "-" + (.number|tostring)
        title: .title
        blueprint: '"githubPullRequest"'
        properties:
          creator: .user.login
          assignees: "[.assignees[].login]"
          reviewers: "[.requested_reviewers[].login]"
          status: .state
          closedAt: .closed_at
          updatedAt: .updated_at
          mergedAt: .merged_at
          prNumber: .number
          link: .html_url
        relations:
          repository: .__repository
          jiraIssue: .title | match("^[A-Za-z]+-[0-9]+") .string

Click Save & Resync to apply the changes

Under the resources key, find the Pull Request block

Replace it with the following YAML configuration to map pull request entities with Jira issues:

Relation mapping (click to expand)

- kind: pull-request
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .head.repo.name + (.id|tostring)
        title: .title
        blueprint: '"githubPullRequest"'
        properties:
          creator: .user.login
          assignees: "[.assignees[].login]"
          reviewers: "[.requested_reviewers[].login]"
          status: .status
          closedAt: .closed_at
          updatedAt: .updated_at
          mergedAt: .merged_at
          prNumber: .id
          link: .html_url
        relations:
          repository: .head.repo.name
          jiraIssue: .title | match("^[A-Za-z]+-[0-9]+") .string

Click Save & Resync to apply the changes

Mapping explanation

The configuration mapping above ingests all pull requests from Github. It then goes ahead to establish a relation between the githubPullRequest entities and the jiraIssue entities 🎉.

Please note that the .head.repo.name property refers to the name of the repository while the .id property refers to the ID of the pull request itself. In our GitHub integration mapping, we have defined these two pieces of information as the identifiers for the githubPullRequest entities.

For the jiraIssue relation, we extract the Jira Issue key from the title of the pull request. Therefore, only pull requests containing the key of the Jira issue will be mapped to their respective Jira issues. Below are few examples and corresponding output:

Pull request title	Jira issue
PORT-4837 \| This is the evening of the day	PORT-4837
GET-14 - This is the evening of the day	GET-14
This is the evening of the day	(no output)

You can also use a search query to match PRs with Jira issues based on multiple criteria.

This approach is particularly useful when you don't know the entity's identifier, but you do know the value of one of its properties.

Follow the steps below to match PRs with Jira issues based on multiple criteria (title, description, branch name). You can customize these matching rules based on your team's conventions and requirements.

Go to your data sources page
Click on your Github integration

GitHub (Ocean)
GitHub (Sunset)

Under the resources key, locate the Pull Request block

Replace it with the following YAML block to map the pull request entities with Jira issues using search queries:

Search query mapping (click to expand)

- kind: pull-request
  selector:
    query: "true"
    states: ["open"]
  port:
    entity:
      mappings:
        identifier: .__repository + "-" + (.number|tostring)
        title: .title
        blueprint: '"githubPullRequest"'
        properties:
          creator: .user.login
          assignees: "[.assignees[].login]"
          reviewers: "[.requested_reviewers[].login]"
          status: .state
          closedAt: .closed_at
          updatedAt: .updated_at
          mergedAt: .merged_at
          prNumber: .number
          link: .html_url
        relations:
          repository: .__repository
          jiraIssue:
            combinator: '"or"'
            rules:
              # Match Jira issue key in PR title
              - property: '"$identifier"'
                operator: '"="'
                value: (.title // "") | match("^[A-Za-z]+-[0-9]+") .string

              # Match Jira issue key in PR description
              - property: '"$identifier"'
                operator: '"="'
                value: (.body // "") | match("[A-Za-z]+-[0-9]+") .string
              
              # Match Jira issue key in PR branch name
              - property: '"$identifier"'
                operator: '"="'
                value: (.head.ref // "") | match("[A-Za-z]+-[0-9]+") .string

Click Save & Resync to apply the changes

Under the resources key, locate the Pull Request block

Replace it with the following YAML block to map the pull request entities with Jira issues using search queries:

Search query mapping (click to expand)

- kind: pull-request
  selector:
    query: "true"
  port:
    entity:
      mappings:
        identifier: .head.repo.name + (.id|tostring)
        title: .title
        blueprint: '"githubPullRequest"'
        properties:
          creator: .user.login
          assignees: "[.assignees[].login]"
          reviewers: "[.requested_reviewers[].login]"
          status: .status
          closedAt: .closed_at
          updatedAt: .updated_at
          mergedAt: .merged_at
          prNumber: .id
          link: .html_url
        relations:
          jiraIssue:
            combinator: '"or"'
            rules:
              # Match Jira issue key in PR title
              - property: '"$identifier"'
                operator: '"="'
                value: (.title // "") | match("^[A-Za-z]+-[0-9]+") .string

              # Match Jira issue key in PR description
              - property: '"$identifier"'
                operator: '"="'
                value: (.body // "") | match("[A-Za-z]+-[0-9]+") .string
              
              # Match Jira issue key in PR branch name
              - property: '"$identifier"'
                operator: '"="'
                value: (.head.ref // "") | match("[A-Za-z]+-[0-9]+") .string

Click Save & Resync to apply the changes

Conclusion

By following these steps, you can seamlessly connect a GitHub pull request with a Jira Issue using either:

Direct identifier mapping (extracting Jira issue keys from PR titles)
Search relations (matching based on multiple criteria like title, description, and branch name)

Choose the approach that best fits your team's workflow and requirements. Search relations offer more flexibility but may require more configuration, while direct identifier mapping is simpler but less flexible.

Automatically resolve tickets with coding agents - the full ticket-to-PR workflow that relies on this PR-to-Jira link for end-to-end traceability.
Enrich pull requests using AI - automatically comment on new PRs with AI-generated context once the PR-Jira link is established.
Smart PR reviewer assignment using AI - use AI to assign the right reviewers based on CODEOWNERS and ownership data.
Manage GitHub pull requests - close, merge, or approve PRs directly from Port.
Port's Jira integration - sync Jira projects and issues into your catalog.

Prerequisites​

Set up data model​

Add the pull request blueprint

Add pull request mapping config

Add the pull request blueprint

Add pull request mapping config

Add Jira issue blueprint​

Add Jira mapping config​

Relate pull requests to Jira issues​

Conclusion​

Related guides​

Prerequisites

Set up data model

Add Jira issue blueprint

Add Jira mapping config

Relate pull requests to Jira issues

Conclusion

Related guides