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

Check out Port for yourself ➜ 

Report a bug

This guide demonstrates how to implement a self-service action in Port that allows you to report bugs in Jira, ensuring prompt issue resolution and improving overall platform reliability.

You can implement this action in three ways:

  • Synced webhook: Interact with Jira's API directly from Port.
  • GitHub workflow: Trigger a GitHub Actions workflow for custom logic.
  • GitLab pipeline: Trigger a GitLab CI/CD pipeline for GitLab-based automation.

Prerequisites​

  • Complete the onboarding process.
  • Access to your Jira organization with permissions to create issues.
  • Port's GitHub Ocean integration installed (required for GitHub Actions implementation).
  • A GitLab project with CI/CD variables and a pipeline trigger token, if you use the GitLab implementation.
  • Jira API token with permissions to create new issues.

Set up data model​

If you haven't installed the Jira integration, you'll need to create a blueprint for Jira issues.
However we highly recommend you install the Jira integration to have these automatically set up for you.

Create the Jira issue 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:

    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"
          },
          "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": {},
      "relations": {}
    }

  5. Click "Save" to create the blueprint.

Set up reporting actions​

You can create Jira bugs by leveraging Port's synced webhooks and secrets to directly interact with the Jira's API. This method simplifies the setup by handling everything within Port.

Add Port secrets

Existing secrets

If you have already installed Port's Jira integration, these secrets should already exist in your portal.
To view your existing secrets:

  1. In your Port application, click on your profile picture .
  2. Choose Credentials, then click on the Secrets tab.

To add these secrets to your portal:

  1. In your Port application, click on your profile picture .

  2. Click on Credentials.

  3. Click on the Secrets tab.

  4. Click on + Secret and add the following secrets:

    • JIRA_API_TOKEN - Your Jira API token

    • JIRA_USER_EMAIL - The email of the Jira user that owns the API token

    • JIRA_AUTH - Base64 encoded string of your Jira credentials. Generate this by running:

      echo -n "your-email@domain.com:your-api-token" | base64

      Replace your-email@domain.com with your Jira email and your-api-token with your Jira API token.

      One time generation

      The base64 encoded string only needs to be generated once and will work for all webhook calls until you change your API token.

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 following JSON configuration into the editor.

    Report a bug action (Webhook) (Click to expand)
    {
      "identifier": "jiraIssue_report_a_bug_webhook",
      "title": "Report a bug (Webhook)",
      "icon": "Jira",
      "description": "Report a bug in Port to our product team using webhook.",
      "trigger": {
        "type": "self-service",
        "operation": "CREATE",
        "userInputs": {
          "properties": {
            "project": {
              "title": "Project",
              "description": "The Jira project where the bug will be created",
              "icon": "Jira",
              "type": "string",
              "blueprint": "jiraProject",
              "format": "entity"
            },
            "description": {
              "icon": "DefaultProperty",
              "title": "Description",
              "type": "string"
            },
            "short_title": {
              "icon": "DefaultProperty",
              "title": "Short title",
              "type": "string"
            }
          },
          "required": [
            "project",
            "short_title",
            "description"
          ],
          "order": [
            "project",
            "short_title",
            "description"
          ]
        }
      },
      "invocationMethod": {
        "type": "WEBHOOK",
        "url": "https://<JIRA_ORGANIZATION_URL>/rest/api/3/issue",
        "agent": false,
        "synchronized": true,
        "method": "POST",
        "headers": {
          "Authorization": "Basic {{.secrets.JIRA_AUTH}}",
          "Content-Type": "application/json"
        },
        "body": {
          "fields": {
            "project": {
              "key": "{{.inputs.project.identifier}}"
            },
            "summary": "{{.inputs.short_title}}",
            "description": {
              "version": 1,
              "type": "doc",
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "{{.inputs.description}}"
                    }
                  ]
                },
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Reported by: {{.trigger.by.user.email}}"
                    }
                  ]
                }
              ]
            },
            "issuetype": {
              "name": "Bug"
            }
          }
        }
      },
      "requiredApproval": false
    }

  5. Click Save.

Configure your Jira url

Replace <JIRA_ORGANIZATION_URL> in the webhook URL with your Jira organization URL (e.g., example.atlassian.net).

Now you should see the Report a bug (Webhook) action in the self-service page. 🎉

Let's test it!​

  1. Go to the Self-service page of your portal.

  2. Choose the action for your implementation:

    • For the GitHub workflow, click on Report a bug.
    • For the synced webhook, click on Report a bug (Webhook).
    • For the GitLab pipeline, click on Report a bug (GitLab).

  3. Fill in the bug details:

    • Select the Jira project where the bug will be created.
    • Enter a short title for the bug.
    • Enter the bug description.

  4. Click Execute.

  5. Wait for the bug to be created in Jira.

For the GitLab path, the action run should trigger the GitLab pipeline and create the Jira issue:

Jira issue created by the GitLab pipeline

More Self Service Jira Actions Examples​