Jira

Project management and issue tracking platform

✅ Ready📖 Documentation Available

Overview

Jira is the leading project management and issue tracking platform developed by Atlassian. It’s widely used by software development teams, IT departments, and business teams to plan, track, and manage work through customizable workflows.

Jira Data Structure

The connector understands Jira’s hierarchical data model: Projects → Issues → Comments/Attachments

Entity	Description
Projects	Top-level containers for organizing work (e.g., Engineering, Marketing)
Issues	Work items including bugs, tasks, stories, epics, and custom types
Comments	Discussion threads attached to issues
Attachments	Files, images, and documents attached to issues
Users & Groups	Team members and their group memberships
Project Roles	Role-based access control for project permissions

What Gets Synced

The connector indexes the following content for AI-powered search:

Issue Content: Summary, description (with rich text/ADF support), status, priority, labels
Issue Metadata: Reporter, assignee, created/updated dates, custom fields
Comments: Full comment threads with author information
Attachments: All file types attached to issues (PDFs, images, documents)
Permissions: Project-level and issue-level access controls are preserved

Configuration Guide

The Jira connector supports two authentication methods. Both sync the same data — pick whichever fits your rollout.

Prerequisite: Email Visibility

Each user in your organization must set their email address to be visible in order for PipesHub to correctly assign permissions and make records visible to them.

This prerequisite applies to both authentication methods (OAuth and API Token). Why email visibility matters. PipesHub uses email addresses to match Jira users with their permissions. If a user’s email is hidden:

PipesHub cannot identify the user when syncing permissions
Records will appear invisible to that user even if they have proper access in Jira
The user won’t be able to see any content they should have access to

How to configure email visibility. Every user must complete these steps in their Atlassian account:

Click your profile picture in the top right → select Account Settings.

Select the Profile and visibility tab.
Scroll down to the Contact section.
In the Who can see this? dropdown for your email address, select either Anyone (recommended) or Your organization.

Do not select “Only you and admins” — this will prevent PipesHub from accessing your email address and matching you to permissions, making all records invisible to you.

📖 Official documentation: Update your profile and visibility settings

This is a per-user setting that must be configured by each individual user. Administrators cannot change this setting for other users. We recommend communicating this requirement to your team during the Jira connector rollout.

Choose an authentication method

Method	Best for
OAuth 2.0 (3LO)	Multi-user / org-wide rollouts, production — per-user refresh tokens, per-user consent, audit trail. Requires Atlassian Developer Console access.
API Token	Single-account setups, quick POCs, or environments where you cannot register an OAuth app. Fastest path to sync.

OAuth 2.0
API Token

Step 1: Access the Atlassian Developer Console

Go to developer.atlassian.com/console/myapps/ and sign in with your Atlassian account (must have admin access to your Jira workspace).
You’ll see the My apps page where you create and manage OAuth 2.0 integrations.

Step 2: Create a new OAuth 2.0 integration

Click Create in the top-right corner.
Select OAuth 2.0 integration from the dropdown.
Fill in the application details:
- Name: Enter a meaningful name (e.g., PipesHub Jira Connector).
- Check the box to agree to Atlassian’s developer terms.
Click Create.

OAuth 2.0 (3LO) integrations use rotating refresh tokens by default, which improves security by limiting token validity and enabling automatic detection of refresh-token reuse.

Step 3: Review the application overview

After creation, you’ll land on the app overview page. It shows:

App ID — your application’s unique identifier
Distribution status — whether the app is shared publicly
Permissions — API scopes configured for the app
Authorization — OAuth 2.0 (3LO) authorization settings

Use the left sidebar to navigate between Permissions, Authorization, and Settings.

Step 4: Configure OAuth 2.0 authorization

In the left sidebar, click Authorization.
Find OAuth 2.0 (3LO) in the authorization types list.
Click Add to enable OAuth 2.0 authorization for your app.

Get the Redirect URL from PipesHub:
- In PipesHub, go to Workspace Settings → Connectors, find Jira, and click + Setup for a new instance.
- The connector panel opens as a right-side drawer. On the Authenticate Instance tab, copy the Redirect URL.

PipesHub Jira Authenticate Instance tab — copy the Redirect URL

Paste the copied URL into the Callback URL field in Atlassian Developer Console.
Click Save changes.

The Callback URL must match exactly between Atlassian Developer Console and PipesHub. Any difference — trailing slash, protocol, casing — causes authentication to fail.

Step 5: Add API permissions

In the left sidebar, click Permissions.
You’ll see a list of available Atlassian APIs.
Add scopes for both User identity API and Jira API.

User Identity API scopesClick Add next to User identity API and select:

Scope	Description
`read:account`	View user profiles (required for user identification)

The offline_access scope is automatically included when you configure OAuth 2.0 (3LO). It enables refresh tokens so scheduled synchronization continues when users are not actively logged in.

Jira API — Classic scopesClick Add next to Jira API. You’ll see two tabs: Classic scopes and Granular scopes. Configure scopes from both.First, the Classic scopes tab:

Scope	Description
`read:jira-work`	Read Jira project and issue data, search issues, attachments, worklogs
`read:jira-user`	Read Jira user information (usernames, emails, avatars)

The connector uses only read-only classic scopes. It does not require any write or manage permissions.

Jira API — Granular scopesNext, the Granular scopes tab. Add these read permissions for fine-grained access:

Scope	Description
`read:user:jira`	View user details
`read:group:jira`	View groups and group members
`read:avatar:jira`	View user and project avatars
`read:audit-log:jira`	Read audit logs (for detecting deleted issues)
`read:application-role:jira`	Read application roles
`read:project-role:jira`	Read project roles and role assignments

Classic scopes (read:jira-work, read:jira-user) provide the primary data access. Granular scopes enable specific features: user lookup, group resolution, audit-log-based deletion detection, and project role permissions.

Step 6: Copy Client ID and Client Secret

In the left sidebar, click Settings.
Scroll to the Authentication details section.
Copy:
- Client ID — used as Application (Client) ID in PipesHub.
- Secret — used as Client Secret in PipesHub. Copy it immediately.

Store the Client ID and Client Secret securely. The secret can be regenerated if needed, but you’ll have to update your PipesHub configuration with the new value.

Step 7: Authenticate Instance tab — enter credentials

The connector drawer in PipesHub has three tabs: Authenticate Instance, Authorize, and Configure Records. Start on the Authenticate Instance tab.

Confirm the Redirect URL matches the Callback URL you saved in Atlassian in Step 4.
If your admin has pre-registered an OAuth app, pick it from the OAuth app dropdown. Otherwise leave it blank and enter credentials manually.
Enter:
- Application (Client) ID — from Step 6
- Client Secret — from Step 6
- Atlassian Site URL — your Jira site URL (e.g., https://your-domain.atlassian.net; no trailing slash)
Click Next to move to the Authorize tab.

Authenticate Instance tab — enter Client ID, Client Secret, and Atlassian Site URL

The Atlassian Site URL targets the specific Jira Cloud site this connector instance will sync. Use the full site URL including https:// (e.g., https://acme.atlassian.net).

Step 8: Authorize tab — complete the OAuth flow

On the Authorize tab, all the OAuth authorization work happens. The tab shows an Authenticate button to kick off the OAuth handshake.

PipesHub Authorize tab with the Authenticate button

Click Authenticate to start the OAuth flow. A popup opens to Atlassian’s authorization page.
Select your Jira site from the dropdown.

Authorize using the same email as your PipesHub account. Using a different email causes permission issues on the PipesHub platform.

Review the permissions requested by the connector and click Accept.

The popup closes and returns you to PipesHub. The connector tile shows an Authenticated badge with a Reauthenticate option.
Click Next to move to the Configure Records tab.

Step 9: Configure Records tab — sync settings, filters, and indexing

On the Configure Records tab, control how the connector syncs and what gets synced.Sync settings — configure your synchronization preferences first:

Sync Strategy — Scheduled or Manual.
Sync Interval — how often to sync (default: 60 minutes).

Scheduled sync runs automatically at the specified intervals. Manual sync requires you to trigger synchronization on-demand.

Sync filters — determine which content is downloaded from Jira. Data excluded by sync filters is never downloaded.

Available sync filters:

Project Keys — Filter by Jira projects.
- Operator: In (include only) or Not In (exclude)
- Selection: searchable dropdown of all your Jira projects (shows names + keys, e.g., “Engineering (ENG)”)
Modified Date — Filter by last modification date. Operators: Is After, Is Before, Is Between.
Created Date — Filter by creation date. Same operators.

The project list is dynamically fetched from your Jira workspace. Type to search and filter; select multiple projects as needed.

Indexing filters — control what synced data gets processed for AI search. All data is synced, but only enabled content types are indexed.

Index Issues (default: enabled) — include issue content (description + comments) in search
Index Issue and Comment Attachments (default: enabled) — include attachments in search

Comments are stored as part of the issue content (not as separate records). When Index Issues is enabled, both issue descriptions and comments are indexed together.

Example configurations:

Sync only Engineering project: Project Keys → Operator In → select “Engineering”
Exclude archived projects: Project Keys → Operator Not In → select archived projects
Recent issues only: Modified Date → Operator Is After → Date 2024-06-01
Index issues but not attachments: disable the Index Issue and Comment Attachments toggle

Click Save to save your configuration. PipesHub confirms the instance is ready with a final dialog — “Instance is configured and ready to sync” — offering two choices: I’ll do it later or Start syncing now.

Instance is configured and ready to sync — I'll do it later or Start syncing now

Choose Start syncing now to kick off the initial sync immediately, or I’ll do it later to enable the connector without an immediate sync. Monitor the Indexing Progress to track sync completion.

Use this method when you want the fastest setup and only need a single user account to sync Jira data. No Atlassian Developer Console access required.

Step 1: Generate an API token in Atlassian

Sign in to id.atlassian.com/manage-profile/security/api-tokens.
Click Create API token.
Give it a meaningful label (e.g., PipesHub Jira Connector), set an expiry if you want, and click Create.

Atlassian shows the token once — click Copy and store it securely.

The API token is shown only once. If you close the dialog without copying it, you’ll have to create a new token.

The token inherits the permissions of the account that created it. Use an account that can read the Jira projects you want to sync — ideally a dedicated integration user rather than a personal account.

Step 2: Authenticate Instance tab — enter credentials

In PipesHub, go to Workspace Settings → Connectors, find Jira, and click + Setup.
The connector panel opens as a right-side drawer with three tabs: Authenticate Instance, Authorize, and Configure Records.
On the Authenticate Instance tab, pick API Token in the Authentication method dropdown.
Enter:
- Base URL — your Jira site URL (e.g., https://your-domain.atlassian.net; no trailing slash)
- Email — your Atlassian account email (the account that created the API token)
- API Token — the token you copied in Step 1
Click Next. PipesHub validates the credentials and advances directly to the Configure Records tab (the Authorize tab is skipped for API Token because the token authenticates on its own).

Authenticate Instance tab with API Token method — Base URL, Email, API Token fields

The Email must match the Atlassian account that owns the API token. Using a different email causes authentication to fail.

Step 3: Configure Records tab — sync settings, filters, and indexing

On the Configure Records tab, control how the connector syncs and what gets synced.Sync settings — configure your synchronization preferences first:

Sync Strategy — Scheduled or Manual.
Sync Interval — how often to sync (default: 60 minutes).

Sync filters — determine which content is downloaded from Jira. Data excluded by sync filters is never downloaded.

Available sync filters:

Project Keys — Filter by Jira projects.
- Operator: In (include only) or Not In (exclude)
- Selection: searchable dropdown of all your Jira projects
Modified Date — Filter by last modification date. Operators: Is After, Is Before, Is Between.
Created Date — Filter by creation date. Same operators.

Indexing filters — control what synced data gets processed for AI search.

Index Issues (default: enabled) — include issue content (description + comments) in search
Index Issue and Comment Attachments (default: enabled) — include attachments in search

Choose Start syncing now to kick off the initial sync immediately, or I’ll do it later to enable the connector without an immediate sync.

Supported Features

The Jira connector syncs the following data from your Jira Cloud workspace:

Projects — all accessible projects with their configurations and permission schemes
Issues — full issue content including summary, description, status, priority, and custom fields
Comments — all comments on issues with author information
Attachments — files attached to issues (images, documents, etc.)
Users — user profiles and account information
Groups — user groups and memberships
Project Roles — role assignments for project access control
Permissions — project permissions and issue-level access controls

Useful Links

Atlassian Developer Console: developer.atlassian.com/console/myapps/
Atlassian API tokens: support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/
OAuth 2.0 (3LO) documentation: developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/
Jira API scopes reference: developer.atlassian.com/cloud/jira/platform/scopes-for-oauth-2-3LO-and-forge-apps/
Jira REST API v3: developer.atlassian.com/cloud/jira/platform/rest/v3/

Troubleshooting

Common issues

Invalid client credentials error (OAuth):

Verify Client ID and Client Secret are correct — no extra spaces
Check that the OAuth app is active in Atlassian Developer Console
Regenerate the secret if necessary and update PipesHub

Callback URL mismatch error (OAuth):

Ensure the Redirect URL in PipesHub exactly matches the Callback URL in Atlassian
Check for trailing slashes, protocol differences (http vs https), or casing
Update both configurations to use the same URL

API token authentication fails:

Confirm the token was copied correctly — no leading/trailing whitespace
The token may have been revoked or expired; create a new one at id.atlassian.com/manage-profile/security/api-tokens
Verify the Email field matches the Atlassian account that created the token
Verify the Base URL matches your Jira site (must include https://, no trailing slash, match *.atlassian.net)

Site URL format issues (OAuth: Atlassian Site URL / API Token: Base URL):

Must include the protocol: https://
Must not include a trailing slash — use https://acme.atlassian.net, not https://acme.atlassian.net/
Must match the actual Jira Cloud site (usually *.atlassian.net)
Do not include paths like /jira or /browse/...

Authorization failed (OAuth):

Verify you’re signing in with an account that has Jira access
Ensure your Jira site is selected during authorization
Check that all required API scopes are configured

No data syncing:

Verify the connector status shows Active
Check that the authenticating user (OAuth) or token-owning user (API Token) has access to Jira projects
Ensure projects are not restricted or archived
Review sync logs for specific error messages

Token expired or sync stopped:

OAuth tokens may expire per Atlassian’s policies; disable and re-enable the connector to re-authenticate
API tokens can be revoked from the Atlassian account page; generate a new one and update the Authenticate Instance tab
Check if the OAuth app is still active in Developer Console

Permission denied for specific issues:

Verify the authenticating user has read access to the issues
Check project permissions in Jira
Review issue security schemes that may limit access

Missing comments or attachments:

Verify indexing filters are enabled for issues and attachments
Check that the user has permission to view comments/attachments
Ensure attachment size limits are not exceeded

If you modify OAuth application settings in Atlassian Developer Console (Client ID, Secret, Callback URL, or scopes), update the configuration in PipesHub and re-authorize. For API tokens, re-enter the token in the Authenticate Instance tab if you regenerate it.

Connector Workflow

Synchronization Process

The Jira connector follows a structured synchronization process to ensure all data is accurately synced and permissions are properly maintained.

Sync overview

The run_sync method executes a complete synchronization cycle in a specific order:

Step	Function	Data Synced	Purpose
1	`_fetch_users()`	Users	Sync all Jira users with their profiles
2	`_sync_user_groups()`	Groups	Sync groups and user-group memberships
3	`_fetch_projects()`	Projects	Fetch projects (filtered if configured)
4	`_sync_project_roles()`	Roles	Sync project role assignments
5	`_sync_project_lead_roles()`	Lead Roles	Assign project lead permissions
6	`_sync_project_issues()`	Issues	Sync issues, comments, and attachments
7	`_handle_issue_deletions()`	Deletions	Detect and remove deleted issues

Full sync vs incremental sync

The connector automatically determines whether to perform a full or incremental sync:Full sync occurs when:

First-time synchronization (no sync checkpoint exists)
Sync filters have been modified since last sync
Manual full sync is triggered

Incremental sync occurs when:

A valid sync checkpoint exists
Filters haven’t changed
Uses JQL queries with updated >= "last_sync_time" to fetch only changes

User & group synchronization

User fetch — retrieves all users from Jira with their account IDs, emails, and display names
Group sync — fetches all groups and their member lists
Membership mapping — creates user-to-group relationships for permission resolution

Project synchronization

Project fetch — retrieves projects (filtered by project keys if configured)
Permission scheme — extracts project permission schemes for access control
Role assignment — syncs project-specific roles (Admin, Developer, Viewer, etc.)
Lead roles — assigns project lead permissions to designated users

Issue synchronization

For each project, the connector:

Builds JQL query — constructs query with date filters and project scope
Batched fetching — retrieves issues in batches (default: 100 per request)
Content processing — parses issue description (ADF format → Markdown with embedded images); extracts metadata (status, priority, labels, etc.)
BlockGroup structure — creates hierarchical content structure:
- Description BlockGroup (index=0): contains issue description with inline attachments
- Comment Thread BlockGroups: each thread gets its own BlockGroup with parent_index=0
- Comment Blocks: individual comments stored as Blocks within their thread BlockGroup
Attachment processing — maps attachments to their correct location (description or specific comments)
Permission assignment — applies project and issue-level permissions

Comments are stored as Blocks within the issue’s BlocksContainer (not as separate records). This enables efficient threaded comment organization and ensures comments are deleted automatically when the parent issue is removed.

Deletion detection

The connector uses Jira’s Audit Log API to detect deleted issues:

Queries audit log for ISSUE_DELETE events since last sync
Identifies deleted issue keys from audit records
Removes issue records from the index
Comments are automatically deleted with the issue (stored as Blocks within the issue)

Checkpoint management

After each successful sync:

Stores the latest issue update timestamp as checkpoint
Records current filter configuration to detect changes
Per-project checkpoints enable resumable syncs on failures

FAQ

Which authentication method should I choose?

	OAuth 2.0	API Token
Best for	Multi-user / org-wide rollouts, production	Single-account setups, quick POCs
Credentials model	Per-user consent, rotating refresh tokens	Single token, long-lived until revoked
Prerequisites	Atlassian Developer Console admin access	Any Atlassian account

Choose OAuth for production and anything that needs per-user attribution. Choose API Token when you cannot register a developer-console app or just want to get syncing quickly. Both methods sync the same data.

What's the difference between Jira Connector and Jira Toolset?

Aspect	Jira Connector	Jira Toolset
Purpose	Sync and index Jira data for search	Enable agents to perform actions in Jira
Data Flow	One-way (import data into PipesHub)	Two-way (read and write via API)
When to Use	Query/search issues, projects, comments	Create issues, update tickets, add comments

Example: Use Jira Connector to search and retrieve existing ticket information. Use Jira Toolset to let agents create new issues or update ticket status.

Queries not returning results. What could be wrong?

Check these in order:

PipesHub email mismatch — the email used to authenticate the Jira connector must match your PipesHub account email. For OAuth, this is the email you signed in with during consent; for API Token, it’s the Email field on the Authenticate Instance tab.
- Fix: reconfigure the connector and authenticate using the same email as your PipesHub account.
Email visibility not set — if your Atlassian email visibility is set to Only you and admins, PipesHub can’t match you to Jira permissions and no records will be visible.
- Fix: set it to Anyone or Your organization (see the Prerequisite: Email Visibility section above).
Verify in All Records — go to All Records in PipesHub and confirm the Jira issues you expect are actually present. If they’re missing, the sync hasn’t reached them yet — check sync status in Settings → Connectors.

Is it possible to index only specific Jira projects?

Yes. On the Configure Records tab, use the Project Keys filter with the In operator and pick the projects you want to include. Or use Not In to exclude specific projects.

Ready to Get Started?

Connect your Jira workspace to PipesHub in just a few minutes. Follow the step-by-step guide above to enable organization-wide project and issue search across all your Jira content.

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

User Management

Deployment

Developer

Additional Resources

Documentation Index

​Jira

​Overview

​Jira Data Structure

​What Gets Synced

​Configuration Guide

​Prerequisite: Email Visibility

​Choose an authentication method

​Step 1: Access the Atlassian Developer Console

​Step 2: Create a new OAuth 2.0 integration

​Step 3: Review the application overview

​Step 4: Configure OAuth 2.0 authorization

​Step 5: Add API permissions

​Step 6: Copy Client ID and Client Secret

​Step 7: Authenticate Instance tab — enter credentials

​Step 8: Authorize tab — complete the OAuth flow

​Step 9: Configure Records tab — sync settings, filters, and indexing

​Step 1: Generate an API token in Atlassian

​Step 2: Authenticate Instance tab — enter credentials

​Step 3: Configure Records tab — sync settings, filters, and indexing

​Supported Features

​Useful Links

​Troubleshooting

​Common issues

​Connector Workflow

​Sync overview

​Full sync vs incremental sync

​User & group synchronization

​Project synchronization

​Issue synchronization

​Deletion detection

​Checkpoint management

​FAQ

​Ready to Get Started?

Jira

Overview

Jira Data Structure

What Gets Synced

Configuration Guide

Prerequisite: Email Visibility

Choose an authentication method

Step 1: Access the Atlassian Developer Console

Step 2: Create a new OAuth 2.0 integration

Step 3: Review the application overview

Step 4: Configure OAuth 2.0 authorization

Step 5: Add API permissions

Step 6: Copy Client ID and Client Secret

Step 7: Authenticate Instance tab — enter credentials

Step 8: Authorize tab — complete the OAuth flow

Step 9: Configure Records tab — sync settings, filters, and indexing

Step 1: Generate an API token in Atlassian

Step 2: Authenticate Instance tab — enter credentials

Step 3: Configure Records tab — sync settings, filters, and indexing

Supported Features

Useful Links

Troubleshooting

Common issues

Connector Workflow

Sync overview

Full sync vs incremental sync

User & group synchronization

Project synchronization

Issue synchronization

Deletion detection

Checkpoint management

FAQ

Ready to Get Started?