> For the complete documentation index, see [llms.txt](https://docs.perfectscale.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perfectscale.io/customize-workflow/ticketing-and-bug-tracking.md).

# Ticketing & Bug Tracking

Easily collaborate with your team by integrating Jira for efficient ticketing and bug tracking, ensuring effective communication and issue management

Jira integration simplifies issue management within clusters and helps you ensure every issue gets properly addressed. With just a few clicks, tickets can be opened and assigned to the proper teams, with the details needed to streamline resolutions and configuration changes. 

{% hint style="info" %}
PerfectScale only supports the SaaS Jira integration.
{% endhint %}

## Configuring Jira integration with the profile

### :tools: **How to create Jira Profile**

There are two options for creating a Profile: [from the Settings](#from-the-settings-tab) tab or directly [from the Overview](#from-the-overview-tab).

#### From the **Settings** tab

Go to the **`Settings`** tab on the left panel -> select **`Integrations`** -> click the **`+Add Integration`** button and select **`Jira`** from the drop-down -> insert the required data.<br>

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FSzGdnbR5ktdWiejDcfHH%2Fjira1.gif?alt=media&amp;token=b7374fc3-7917-4e07-b1e9-86b5df1f2fd9" alt=""><figcaption><p>Jira profile from settings</p></figcaption></figure>

#### From the **Overview** tab

Go to the **`Overview`** tab on the left panel -> find the cluster to which you want to apply the **`Profile`** and click **`gear`** button -> go to **`Customizations`** -> find **`Integrations`** and click the **`Ticketing & Bug Tracking`** drop-down list -> click the **`Add New Profile`** button -> insert the required data.<br>

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2F3IG3kKKNMbizGwuVrj32%2Fjira2.gif?alt=media&amp;token=5df352e7-8a17-408d-be12-429ca1139900" alt=""><figcaption><p>Jira profile from overview</p></figcaption></figure>

#### Jira Profile Configuration

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FxFIIti9boIRhvYYsJlqA%2FGroup%201000001775%20(1).png?alt=media&amp;token=5e7ed0fd-49de-4259-a448-ee68e9964194" alt=""><figcaption><p>Jira profile configuration</p></figcaption></figure>

{% stepper %}
{% step %}
**Name your profile**
{% endstep %}

{% step %}
**Configure the profile**

`jira_user`: Email address of the user creating the profile. We recommend creating a separate JIRA user for PerfectScale.

`jira_secret`: API token to authenticate with an Atlassian cloud product.

{% hint style="info" %}
The API token in the profile must have the **Jira Administrator global permission**.
{% endhint %}

* Go to <https://id.atlassian.com/manage-profile/security/api-tokens> and click **`Create API token`** button. <br>

  <figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FcMNnFW4jbRU7seUv8yxj%2FGroup%204716%20(1).png?alt=media&amp;token=c6ac853e-8fa3-4063-9c63-66c161d4fc6e" alt="" width="375"><figcaption><p>New API token</p></figcaption></figure>
* Insert the label and click **`Create`** button.<br>

  <figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FRRtWwj1QpL3SntYayZlX%2Fimage.png?alt=media&amp;token=43d8734b-3c73-4540-9cdc-bfda445705c7" alt="" width="249"><figcaption><p>Create an API token</p></figcaption></figure>
* Copy the created API token and put it in the `jira_secret` field.

{% hint style="info" %}
To generate the API token, you need to use the Jira account that is associated with the **`Integration Profile`**(account specified in `jira_user`).
{% endhint %}

`jira_url`: Your Jira host name. For example: xxx.atlassian.net, where **xxx** - a corporate domain.

{% hint style="info" %}

* Connections are always made over HTTPS, so self-hosted Jira instances must be reachable over HTTPS. `http://` connections are refused.
* `https://` is optional and and does not need to be specified.&#x20;
* Do not add a path or query parameters.
  {% endhint %}

{% hint style="info" %}
Non-standard ports are supported. For example: `jira.mycompany.com:8443`.
{% endhint %}

`jira_project`: Jira project where tickets will be created.<br>

`jira_issue_type`: The type of a Jira ticket.<br>

`jira_sumary` : The summary of a Jira ticket.<br>

`jira_assignee` : The default assignee (member ID) of a Jira ticket.

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FdlA4rijfgF9pA17dZUfs%2FGroup%204716.png?alt=media&amp;token=12644c05-75ab-4749-b502-cd2bc9539a44" alt="" width="375"><figcaption><p>Member id</p></figcaption></figure>

`jira_resolution`(optional): Set **true** to assign the resolution reason when closing a ticket in the specified **jira\_project**.<br>

`jira_custom_fields`(optional): Specify the ID of the required Jira ticket field that is not included in the default setup. Use the following format for the custom field ID:&#x20;

```
jira_custom_fields:
  customfield_XXXXX: 'DevOps Team'
```

Learn how to get a field ID [here](#how-to-get-jira-custom-field-id).
{% endstep %}

{% step %}
**Set as default**

Optionally, you can set the profile as the default by selecting the **`Set as default`** checkbox. The default profile will be automatically assigned to clusters.

{% hint style="info" %}
The manually assigned profile takes priority over the default one.
{% endhint %}
{% endstep %}

{% step %}
**Validate Jira profile configuration**

Click on the **`Test Integration`** button to validate if Jira profile is configured properly. You will receive one of the following responses:

* Jira Configured Correctly &#x20;
* Jira Configured Wrongly&#x20;
  {% endstep %}

{% step %}
**Save profile**

Click the **`Save`** button to save the progress.
{% endstep %}
{% endstepper %}

#### How to get Jira custom field ID

A simple method to obtain a Jira custom field ID without requiring extra permissions is to inspect the relevant Jira issue that includes this field. Follow the next simple steps:

1. Open an issue (Jira ticket) with the custom field for which you want to find the ID.
2. Right-click on the field name and select `Inspect`.
3. On the Developer Tools panel, you will find the name and ID for your custom field.

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2FcfbChowsIDwlWcUU6xSG%2FGroup%201000001769.png?alt=media&amp;token=062c9198-c374-4753-ad16-f13a4a40296f" alt=""><figcaption><p>Jira custom field idApplying resiliency alerts profile to a single cluster</p></figcaption></figure>

{% hint style="info" %}
You can easily set up multiple custom fields within one profile by listing them under `jira_custom_fields`. For example:

```yaml
jira_custom_fields:
  customfield_00000: 'DevOps Team'
  customfield_00001: 'Resource anomaly fix'
  customfield_00002: 'Under-provisioning'
```

{% endhint %}

### :tools: **How to apply Jira Profile**

#### Apply to a single cluster

To apply the **`Profile`** to the cluster, go to the **`Overview`** tab on the left panel -> find the cluster to which you want to apply the **`Profile`** and click **`gear`** button -> go to **`Customizations`** -> find **`Integrations`** and click the **`Ticketing & Bug Tracking`** drop-down list -> select the needed profile.<br>

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2Fr9HwbtqpB9jUr9wZESiw%2Fjira%20connect.gif?alt=media&amp;token=dfbbc46e-deca-42e6-afa8-cd5877fb93b6" alt=""><figcaption><p>Applying Jira profile to a single cluster</p></figcaption></figure>

#### Apply to multiple clusters

To apply a profile to multiple clusters from a single view, use the **`Manage Assignments`** feature. \
\
Go to the **`Settings`** tab on the left panel -> select **`Integrations`** -> click the **`Manage Assignments`** button -> apply the profile for the needed clusters in the **`Ticketing & Bug Tracking`** section -> click the **`Save Changes`** button.

<figure><img src="https://1573387604-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FABMqnYtsOO44JmQTVSnn%2Fuploads%2F7DiyJiUp3vzyzzxorJCx%2FJira_multiple.gif?alt=media&amp;token=7f8b487e-a1f1-4138-8f2d-9b5ecbce80c0" alt=""><figcaption><p>Applying Jira profile to multiple clusters</p></figcaption></figure>

## Configuring Jira integration with CR

To enable Jira ticketing, you need to define and apply a Custom Resource (CR) with the required Jira parameters. This approach allows you to manage Jira ticketing directly through Kubernetes manifests.&#x20;

{% hint style="warning" %}
The Custom Resource (CR) must be created in the `perfectscale` namespace.
{% endhint %}

### Setup instructions

1. Navigate to your Jira instance (e.g., <https://mycompany.atlassian.net>)
2. Create a bot user or use an existing user account.

{% hint style="info" %}
We recommend you create a separate JIRA user for PerfectScale.
{% endhint %}

3. Generate an API token for the user.
4. [Copy the API token](https://id.atlassian.com/manage-profile/security/api-tokens) (you will need it for CR configuration).
5. Apply the Jira API token secret.
6. Configure a CR.

{% hint style="info" %}
You may need to use custom fields for the integration. This configuration is optional, and you can learn more about it [here](#how-to-get-jira-custom-field-id).
{% endhint %}

Apply the **Jira API token secret** first:

```yaml
Jira API Token Secret (apply this first)
apiVersion: v1
kind: Secret
metadata:
  name: jira-credentials
  namespace: perfectscale
type: Opaque
stringData:
  api-token: "your-jira-api-token-here"
```

{% hint style="info" %}
Ensure that the secret is created in the same namespace as the exporter -  `perfectscale`.
{% endhint %}

Configure the CR:

```yaml
apiVersion: perfectscale.io/v1
kind: ClusterSettings
metadata:
  name: cluster-settings-main
  namespace: perfectscale
spec:
  profiles:
    integrations:
      - type: jira
        name: infrastructure-tickets
        assigned: true
        value:
          jira_url: "https://mycompany.atlassian.net"
          jira_user: "perfectscale-bot@mycompany.com"
          jira_secret_from:
            secretKeyRef:
              name: jira-credentials
              key: api-token
          jira_project: "INFRA"
          jira_issue_type: "Bug"
          jira_summary: "PerfectScale discovered issue(s) with workload"
          jira_assignee: ""
          jira_resolution: false
          # Optional: custom fields (not included in the default setup)
          # jira_custom_fields:
          #   customfield_10001: "DevOps Team"
          #   customfield_10002: "Resource anomaly fix"
```

⚙️ **CR parameters:**

<table><thead><tr><th width="251.94921875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong><code>jira_url</code></strong></td><td>Corporate Jira URL. <br><strong>Example</strong>: https://xxx.atlassian.net</td></tr><tr><td><strong><code>jira_user</code></strong></td><td>Email address of the user creating the CR.</td></tr><tr><td><strong><code>jira_secret_from</code></strong></td><td>API token to authenticate with an Atlassian cloud product.</td></tr><tr><td><strong><code>jira_project</code></strong></td><td>Jira project where you want tickets to be created.</td></tr><tr><td><strong><code>jira_issue_type</code></strong></td><td>The desired type of a Jira ticket.</td></tr><tr><td><strong><code>jira_summary</code></strong></td><td>The desired summary of a Jira ticket.</td></tr><tr><td><strong><code>jira_assignee</code></strong></td><td>The default assignee (member ID) of a Jira ticket.</td></tr><tr><td><strong><code>jira_resolution</code></strong>   </td><td>(optional) Set <code>true</code> to assign the resolution reason when closing a ticket in the specified jira_project.</td></tr><tr><td><strong><code>jira_custom_fields</code></strong></td><td>(optional) Specify additional Jira ticket field (field ID) that is not included in the default setup.</td></tr></tbody></table>