> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gradial.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Integration

> Connect Gradial to Jira Cloud or Jira Server / Data Center to automatically ingest issues and sync results back to tickets.

**What you can do:**

* Ingest Jira issues into Gradial with full metadata
* Filter by project, status, issue type, labels, or custom JQL
* Trigger Gradial execution when tickets match your criteria
* Write results — previews, links, comments — back to the Jira ticket
* Sync attachments from Jira into Gradial (Forge OAuth)

<Warning>
  Due to Atlassian Forge app limitations, Gradial **cannot upload attachments back to Jira** when using Forge OAuth. Attachments sync Jira → Gradial only, not in reverse.
</Warning>

***

## Prerequisites

**Service account requirements:**

* A dedicated Jira account for integrations — not a personal user
* Must be licensed and discoverable in Jira (so Gradial can assign issues)
* Must have access to all projects and issues you plan to sync

**Required permissions for the service account:**

| Scope               | Permissions required                                                  |
| ------------------- | --------------------------------------------------------------------- |
| **Project / Space** | Project: Read, Sprint: Read, Board: Read                              |
| **Issues**          | Read / Write across all issue types (Story, Task, Bug, Epic, Subtask) |
| **Comments**        | Read / Write / Delete                                                 |
| **Attachments**     | Read / Write / Delete                                                 |
| **Issue Links**     | Read                                                                  |
| **Users**           | Read                                                                  |

Permissions may come from global permissions, project roles, or issue security schemes. See [Atlassian OAuth scopes documentation](https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps) for additional detail.

***

## Authentication options

| Method                         | Best for                        | Requirements                                              |
| ------------------------------ | ------------------------------- | --------------------------------------------------------- |
| **Cloud — Email + API Token**  | Standard Jira Cloud setups      | Email address + API token from Atlassian Account Settings |
| **Cloud — Forge OAuth App**    | Enterprise / secure deployments | Gradial Forge App installed on your Jira instance         |
| **Server / Data Center — PAT** | Self-hosted Jira deployments    | Personal Access Token from the service account            |

***

## Connect Jira to Gradial

Go to **Integrations** in the Gradial sidebar, find Jira under **Ticket System Integrations**, and click **Connect**. Then follow the steps for your authentication method.

### Option A — Jira Cloud (Email + API Token)

1. Enter your **Jira Base URL** (e.g., `https://your-company.atlassian.net`)
2. Enter the **Email Address** of your service account
3. Generate an API token at `https://id.atlassian.com/manage-profile/security/api-tokens`
4. Paste the token into **API Token**
5. Click **Validate Connection**

### Option B — Jira Cloud (Forge OAuth App)

1. Select **Jira Cloud (Forge OAuth App)** as your authentication type
2. Enter your **Jira Base URL** and service account **Email Address**
3. Enter an **API Token** to authorize the initial installation
4. Click **Install Forge App** and approve the Gradial app in the Jira permissions dialog
5. Once **Forge App Installed** is confirmed, click **Validate Connection**

### Option C — Jira Server / Data Center (PAT)

1. Enter your **Jira Base URL**
2. Paste the **Personal Access Token** generated from the service account's settings
3. Click **Validate Connection**

***

## Configure routes

Once connected, create routes to define which Jira issues sync into which Gradial workspaces. Jira supports project, issue type, label, and JQL filters.

[Configure Routes →](/docs/integrations-administration-and-setup/how-gradial-works-with-ticketing-systems/routing-tickets)

**Optional — Assign Back to Reporter:** When enabled, Gradial automatically reassigns a Jira issue back to the original reporter upon completion, so tickets don't stay assigned to the service account.

***

## Troubleshooting

| Issue                           | Likely cause                                | Fix                                                                     |
| ------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------- |
| No issues syncing               | Service account missing project permissions | Confirm the account has issue Read access for all target projects       |
| Authentication fails            | Invalid or expired API token                | Regenerate the token; confirm the Forge app is authorized if applicable |
| Attachments not syncing to Jira | Forge OAuth limitation                      | Expected behavior — Forge OAuth syncs Jira → Gradial only               |
| Issues stuck pending            | Jira service account not licensed           | Ensure the account is active and discoverable                           |

Contact your Gradial Product Specialist if issues persist.