Skip to main content

​
Overview

Gradial’s Jira integration allows you to sync issues from your Jira instance into Gradial to power collaboration, reporting, and automation across your marketing workflows.

​
With this integration, you can:

  • Ingest Jira issues into Gradial with full metadata
  • Filter by project, team, status, issue type, or custom JQL
  • Build queries using Gradial’s visual builder or raw JQL
  • Trigger Gradial automations when Jira tickets change
  • Surface Jira ticket status directly inside Gradial workspaces
  • (Forge OAuth) Sync attachments from Jira to Gradial
Due to Atlassian Forge app limitations, Gradial cannot upload attachments back to Jira when using the Forge OAuth authentication type. Attachments will sync from Jira → Gradial, but not in the reverse direction.

​
Prerequisites

Before connecting Jira to Gradial, gather the following based on your authentication type.

​
Required for all setups

  • Jira Base URL – e.g., https://your-company.atlassian.net
  • Jira service account – the Jira identity Gradial will connect as
    • This should be a dedicated account intended for integrations, not a personal user
    • Gradial does not need access to the inbox for this account
    • The account must be licensed and discoverable in Jira (so Gradial can assign issues)
    • Must have access to all Jira projects and issues you plan to sync

​
Required permissions for the Jira service account

Your Jira service account must have the following access:

​
Project / Space permissions

  • Project: Read
  • Sprint: Read
  • Board: Read
  • Space/Project (if Confluence integration applies): Read

​
Issue-level permissions

Across all issue types (Story, Task, Bug, Epic, Subtask, etc.):
  • Issue: Read / Write
  • Comment: Read / Write / Delete
  • Attachment: Read / Write / Delete
  • Issue Link: Read
  • User: Read
These permissions may come from:
  • Global permissions
  • Project roles
  • Issue security schemes
For additional detail, see Atlassian’s documentation on OAuth scopes for Forge apps and OAuth 2.0 integrations:
https://developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps

​
Optional (for advanced filtering)

  • Project keys (e.g., WEB, CMS)
  • Statuses to ingest (e.g., To Do, In Progress, Done)
  • Custom field names and values (e.g., Page Type: Landing Page)

​
Authentication Types

Gradial supports multiple Jira authentication methods depending on your environment:

Jira Cloud — Email + API Token

Uses a traditional Jira Cloud API token generated from Atlassian Account Settings.

Jira Cloud — Forge OAuth App

Uses the Gradial Forge App for OAuth-based authentication and permissioned access.

Jira Server / Data Center — Personal Access Token (PAT)

Used for self-hosted Jira deployments.

​
Connect Jira to Gradial

​
1. Open the Jira integration

  1. Go to Integrations in the Gradial sidebar.
  2. Under Ticket System Integrations, click Connect on the Jira card.

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

​
Required fields

  • Jira Base URL
  • Email Address
  • API Token

​
Steps

  1. Enter your Jira Base URL.
  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)

​
Required fields

  • Jira Base URL
  • Email Address
  • API Token (used only during Forge app installation)

​
Steps

  1. Select Jira Cloud (Forge OAuth App) as your authentication type.
  2. Enter your Jira Base URL and Email Address.
  3. Enter an API Token to authorize installation.
  4. Click Install Forge App.
  5. Approve the Gradial Forge App in the Jira permissions dialog.
  6. After installation, you will see Forge App Installed.
  7. Click Validate Connection to complete OAuth authorization.

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

​
Required fields

  • Jira Base URL
  • Personal Access Token
  1. Enter your Jira Base URL.
  2. Paste your PAT.
  3. Validate the connection.

​
2. Configure Routes

Routes define which Jira issues sync into which Gradial workspaces.

​
Create a Route

  1. Click Add Rule in the Route Table.
  2. Enter a Rule Name and optional Description.
  3. Choose your query mode:
    • Visual Builder
    • Raw JQL
  4. If using JQL, paste your query (e.g., project = WEB AND status = "In Progress").
  5. Click Test Query to preview matching issues.
Gradial will show sample issues so you can confirm the query is correct.

​
3. Select Gradial Destination

Under Gradial Destination:
  • Workspace – where Jira issues will appear inside Gradial
  • Environment – e.g., Production, Staging
  • Assign Back to Reporter (optional)
    • When enabled, Gradial automatically reassigns the Jira issue back to the original reporter upon completion

​
4. Save Your Configuration

Click Save to activate the integration.
Gradial will begin syncing issues based on your configured rules.

​
Troubleshooting

​
No issues are syncing

  • Confirm the service account has the correct project and issue permissions
  • Ensure the Forge App is installed (if applicable)
  • Validate your JQL query
  • Broadly test with a simpler query (e.g., project = XYZ)

​
Authentication fails

  • Check your Jira Base URL
  • Verify the API token
  • Ensure the Forge app is authorized for your Jira site
  • Confirm your service account is active and licensed
  • Confirm Gradial access has been authorized (if behind firewall)

​
Support

If you need help configuring or troubleshooting the integration,
please contact your Gradial Product Specialist.