Connect GitHub Pull Request with Jira Issue

This guide aims to cover how to connect a GitHub pull request with a Jira Issue to understand the scan results of your PR.

Prerequisites

This guide assumes you have a Port account and that you have finished the onboarding process.
Ensure you have Jira installed and configured in your environment
Ensure you have a registered organization in Port and your Port user role is set to Admin.
You will need an accessible k8s cluster. If you don't have one, here is how to quickly set-up a minikube cluster.
Helm - required to install a relevant integration.

Integrate GitHub resources with Port

The goal of this section is to fill the software catalog with data directly from your GitHub organization. Port's GitHub app allows you to import repositories, pull requests, workflows, teams and other GitHub objects. For the purpose of this guide, we shall focus on pull requests (PR) object only. Follow the steps below to ingest your PR data to Port.

Note

For the GitHub app installation you will need to have a registered organization in Port and your Port user role must be set to Admin (see prerequisites).

Go to your Builder
Create a GitHub pull request blueprint using this 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": {}
    }

Install Port's GitHub app by following the installation guide
Now that the integration is installed successfully, we need to ingest githubPullRequest data from the GitHub organization into the software catalog. This can be done by adding some mapping logic. Go to your data sources page, and click on your GitHub integration:

Add the following YAML block into the editor to ingest pull request data. Then click Save & Resync:

Relation mapping (click to expand)

resources:
    - kind: pull-request
    selector:
        query: "true"
    port:
        entity:
        mappings:
        identifier: ".head.repo.name + '-' + (.number|tostring)" # The Entity identifier will be the repository name + the pull request number
        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"

You should now be able to see your GitHub pull requests ingested successfully in the software catalog.

Integrate Jira into Port

The goal of this section is to bring our Jira issues into Port. Port's Jira integration (powered by Ocean) allows you to import projects and issues from your Jira account into Port. The integration automatically creates blueprints and entities for these resources.

Note

For this installation you will need Helm and a running K8s cluster (see prerequisites).

Install Port's Jira integration using Helm, by running the command below in your terminal.

Replace CLIENT_ID and CLIENT_SECRET with your credentials (get them here).
Replace jiraHost with the host URL to your Jira application. To obtain it, simply copy it from the url address bar when you are on your Jira dashboard. It has the format, <org name>.atlassian.com. If you are on Jira self-hosted, you can simply use the host URL where your Jira application is hosted.
Replace atlassianUserEmail with the email associated with your Atlassian account.
Replace atlassianUserToken with a token generated from your Atlassian account. Follow the Atlassian guide on using personal access tokens

Installation command (click to expand)

helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
helm upgrade --install my-jira-integration port-labs/port-ocean \
	--set port.clientId="PORT_CLIENT_ID"  \  # REPLACE VALUE
	--set port.clientSecret="PORT_CLIENT_SECRET"  \  # REPLACE VALUE
	--set initializePortResources=true  \
	--set integration.identifier="my-jira-integration"  \
	--set integration.type="jira"  \
	--set integration.eventListener.type="POLLING"  \
	--set integration.secrets.jiraHost="MY_JIRA_HOST"  \  # REPLACE VALUE
	--set integration.secrets.atlassianUserEmail="MY_ATLASSIAN_USER_EMAIL"  \  # REPLACE VALUE
	--set integration.config.atlassianUserToken="MY_ATLASSIAN_USER_TOKEN"  # REPLACE VALUE

Great! Now that the integration is installed, we should see some new components in Port:

Go to your Builder, you should now see four new blueprints created by the integration - Jira Project and Jira Issue.
Go to your Software catalog, click on Jira Issue in the sidebar, you should now see new entities created for all your Jira issues

Create the Jira Issue relation

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. Go to your data sources page, and click on your Github integration:

Under the resources key, locate the Pull Request block and replace it with the following YAML block to map the pull request entities with Jira issues. Then click Save & Resync:

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

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)

Conclusion

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

More relevant guides and examples:

Integrate GitHub resources with Port​

Integrate Jira into Port​

Create the Jira Issue relation​

Conclusion​

Integrate GitHub resources with Port

Integrate Jira into Port

Create the Jira Issue relation

Conclusion