Create a GitHub issue

Available Github Integrations

This guide includes one or more steps that require integration with GitHub.
Port supports two GitHub integrations:

• GitHub (Legacy) - uses a GitHub app, which is soon to be deprecated.
• GitHub (Ocean) - uses the Ocean framework, recommended for new integrations.

Both integration options are present in this guide via tabs, choose the one that fits your needs.

Overview

This guide will demonstrate how to implement a self-service action that creates GitHub issues directly from Port using the GitHub integration.

This functionality streamlines project management by enabling users to create issues without leaving Port.

Prerequisites

• Complete the onboarding process.
• Access to your GitHub organization with permissions to manage issues.
• Install Port's GitHub integration:

GitHub (Legacy)

Port's GitHub app needs to be installed.

GitHub (Ocean)

Install GitHub Ocean.

Set up data model

If you haven't installed the GitHub integration, you will need to manually create a blueprint for GitHub repository.
We highly recommend that you install the GitHub integration to have such resources automatically set up for you.

Create the 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": "Microservice",
   "schema": {
       "properties": {
       "readme": {
           "title": "README",
           "type": "string",
           "format": "markdown"
       },
       "url": {
           "title": "Repository URL",
           "type": "string",
           "format": "url"
       },
       "defaultBranch": {
           "title": "Default branch",
           "type": "string"
       }
       },
       "required": []
   },
   "mirrorProperties": {},
   "calculationProperties": {},
   "relations": {}
   }

5. Click Save to create the blueprint.

Implementation

You can create GitHub issues by leveraging Port's GitHub integration to dispatch workflows that interact with GitHub's REST API.

Add Port secrets

Add the following secrets to your Port application (for passing the target org to the workflow):

1. Click on your profile picture in the top right corner of your Port application.
2. Click on Credentials.
3. Click on the Secrets tab.
4. Click on + Secret and add:
   • GITHUB_ORG: Your GitHub organization or username.

Add GitHub repository secrets

In your GitHub repository, go to Settings > Secrets and add:

• PORT_CLIENT_ID - Port Client ID learn more.
• PORT_CLIENT_SECRET - Port Client Secret learn more.
• GH_TOKEN - A Classic Personal Access Token with the repo scope to create issues.

Set up self-service action

Follow these steps to create the self-service action:

1. Head to the self-service page.
2. Click on the + New Action button.
3. Click on the {...} Edit JSON button.
4. Copy and paste the JSON configuration for your integration type into the editor:

GitHub (Legacy)

Create GitHub Issue (Click to expand)

Replace the variables

• <GITHUB-ORG> - your GitHub organization or user name.
• <GITHUB-REPO-NAME> - the repository where the workflow file is stored.

{
  "identifier": "create_github_issue",
  "title": "Create GitHub Issue",
  "icon": "Github",
  "description": "A self service action to open a GitHub repository issue with labels",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "title": {
          "icon": "DefaultProperty",
          "type": "string",
          "title": "Issue Title"
        },
        "labels": {
          "type": "array",
          "title": "Label",
          "description": "issue label",
          "default": ["bug"],
          "items": {
            "enum": [
              "bug",
              "enhancement",
              "documentation",
              "dependencies",
              "question",
              "invalid",
              "duplicate"
            ],
            "enumColors": {
              "bug": "red",
              "enhancement": "turquoise",
              "documentation": "blue",
              "dependencies": "purple",
              "question": "lime",
              "invalid": "yellow",
              "duplicate": "orange"
            },
            "type": "string"
          }
        },
        "content": {
          "type": "string",
          "title": "Content",
          "format": "markdown"
        }
      },
      "required": ["title"],
      "order": ["title", "content", "labels"]
    },
    "blueprintIdentifier": "githubRepository"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB-ORG>",
    "repo": "<GITHUB-REPO-NAME>",
    "workflow": "create-github-issue.yml",
    "workflowInputs": {
      "title": "{{ .inputs.title }}",
      "content": "{{ .inputs.content }}",
      "labels": "{{ .inputs.labels }}",
      "target_org": "{{ .secrets.GITHUB_ORG }}",
      "target_repo": "{{ .entity.identifier }}",
      "port_context": {
        "blueprint": "{{ .action.blueprint }}",
        "entity": "{{ .entity }}",
        "runId": "{{ .run.id }}",
        "trigger": "{{ .trigger }}"
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false
}

GitHub (Ocean)

Create GitHub Issue (Click to expand)

Replace the variables

• <GITHUB-ORG> - your GitHub organization or user name.
• <GITHUB-REPO-NAME> - the repository where the workflow file is stored.
• <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration ID.

{
  "identifier": "create_github_issue",
  "title": "Create GitHub Issue",
  "icon": "Github",
  "description": "A self service action to open a GitHub repository issue with labels",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "title": {
          "icon": "DefaultProperty",
          "type": "string",
          "title": "Issue Title"
        },
        "labels": {
          "type": "array",
          "title": "Label",
          "description": "issue label",
          "default": ["bug"],
          "items": {
            "enum": [
              "bug",
              "enhancement",
              "documentation",
              "dependencies",
              "question",
              "invalid",
              "duplicate"
            ],
            "enumColors": {
              "bug": "red",
              "enhancement": "turquoise",
              "documentation": "blue",
              "dependencies": "purple",
              "question": "lime",
              "invalid": "yellow",
              "duplicate": "orange"
            },
            "type": "string"
          }
        },
        "content": {
          "type": "string",
          "title": "Content",
          "format": "markdown"
        }
      },
      "required": ["title"],
      "order": ["title", "content", "labels"]
    },
    "blueprintIdentifier": "githubRepository"
  },
  "invocationMethod": {
    "type": "INTEGRATION_ACTION",
    "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
    "integrationActionType": "dispatch_workflow",
    "integrationActionExecutionProperties": {
      "org": "<GITHUB-ORG>",
      "repo": "<GITHUB-REPO-NAME>",
      "workflow": "create-github-issue.yml",
      "workflowInputs": {
        "title": "{{ .inputs.title }}",
        "content": "{{ .inputs.content }}",
        "labels": "{{ .inputs.labels }}",
        "target_org": "{{ .secrets.GITHUB_ORG }}",
        "target_repo": "{{ .entity.identifier }}",
        "port_context": {
          "blueprint": "{{ .action.blueprint }}",
          "entity": "{{ .entity }}",
          "runId": "{{ .run.id }}",
          "trigger": "{{ .trigger }}"
        }
      },
      "reportWorkflowStatus": true
    }
  },
  "requiredApproval": false
}

5. Create a workflow file under .github/workflows/create-github-issue.yml with the following content:

Create GitHub Issue workflow (Click to expand)

create-github-issue.yml

name: Create GitHub Issue

on:
  workflow_dispatch:
    inputs:
      title:
        required: true
        type: string
      content:
        required: false
        type: string
      labels:
        required: false
        type: string
      target_org:
        required: true
        type: string
      target_repo:
        required: true
        type: string
      port_context:
        required: true
        type: string

jobs:
  create-issue:
    runs-on: ubuntu-latest
    steps:
      - name: Inform starting of issue creation
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          logMessage: |
            Creating a GitHub issue... ⛴️

      - name: Create GitHub issue
        env:
          GH_TOKEN: ${{ secrets.GH_TOKEN }}
        run: |
          LABELS_INPUT='${{ inputs.labels }}'
          LABELS_JSON=$(echo "$LABELS_INPUT" | jq -c 'if type == "string" then fromjson | (if type == "array" then . else [.] end) else (if type == "array" then . else [.] end) end' 2>/dev/null || echo "[\"bug\"]")
          PAYLOAD=$(jq -n \
            --arg title "${{ inputs.title }}" \
            --arg body "${{ inputs.content }}" \
            --argjson labels "$LABELS_JSON" \
            '{title: $title, body: $body, labels: $labels}')
          RESPONSE=$(curl -s -w "\n%{http_code}" -X POST \
            -H "Accept: application/vnd.github+json" \
            -H "Authorization: Bearer $GH_TOKEN" \
            -H "Content-Type: application/json" \
            -d "$PAYLOAD" \
            "https://api.github.com/repos/${{ inputs.target_org }}/${{ inputs.target_repo }}/issues")
          HTTP_STATUS=$(echo "$RESPONSE" | tail -n1)
          BODY=$(echo "$RESPONSE" | sed '$d')
          echo "HTTP Status: $HTTP_STATUS"
          if [ "$HTTP_STATUS" -ge 200 ] && [ "$HTTP_STATUS" -lt 300 ]; then
            echo "Issue created successfully."
            echo "$BODY" | jq -r '.html_url' >> $GITHUB_STEP_SUMMARY
          else
            echo "Failed to create issue. Response: $BODY"
            exit 1
          fi

      - name: Inform completion
        uses: port-labs/port-github-action@v1
        with:
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          operation: PATCH_RUN
          runId: ${{ fromJson(inputs.port_context).runId }}
          logMessage: |
            GitHub issue created! ✅

6. Click Save.

Now you should see the Create GitHub Issue action in the self-service page. 🎉

Let's test it!

1. Head to the self-service page of your portal.

2. Choose the Create GitHub Issue action:

3. Enter the required information:

   • Issue name.
   • Description of the issue.
   • Label.

4. Click on Execute.

5. Done! Wait for the issue to be created in GitHub.