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)
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.
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 |
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)
- Enter your Jira Base URL (e.g.,
https://your-company.atlassian.net)
- Enter the Email Address of your service account
- Generate an API token at
https://id.atlassian.com/manage-profile/security/api-tokens
- Paste the token into API Token
- Click Validate Connection
Option B — Jira Cloud (Forge OAuth App)
- Select Jira Cloud (Forge OAuth App) as your authentication type
- Enter your Jira Base URL and service account Email Address
- Enter an API Token to authorize the initial installation
- Click Install Forge App and approve the Gradial app in the Jira permissions dialog
- Once Forge App Installed is confirmed, click Validate Connection
Option C — Jira Server / Data Center (PAT)
- Enter your Jira Base URL
- Paste the Personal Access Token generated from the service account’s settings
- Click Validate Connection
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 →
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 |
