> ## 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

> 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.

***

## Reporting on your Jira data

With Jira connected, you can ask Grady to build a [custom app](/docs/insights/custom-apps) that reports against it — what's open, what's blocked, and what's been waiting longest, grouped however your team works — without exporting to a spreadsheet or waiting on someone to build a Jira view.

Because the app queries the connected system on refresh, it reflects the current state of Jira rather than a snapshot.

***

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.