Jira | Alephant Documentation

What it indexes

The Jira connector turns each matching issue into one searchable document. It can index every issue visible to the credential, one project selected by project key, or issues matched by a custom JQL query. OpenCore adds its own updated time window to every indexing query.

Issue data	Indexing behavior
Content	The issue description and comments are combined into one text section. A comment is omitted only when Jira returns `comment.author.emailAddress` and it is a case-sensitive exact match for a Comment Email Blacklist entry. If the email is absent, the comment remains indexed.
Metadata and hierarchy	The key, summary, project, type, status, priority, resolution, labels, dates, reporter, assignee, and parent are retained when available. Projects and epics appear as hierarchy nodes.
Attachments	Attachment files and their extracted text are not fetched by this connector.
Filters and limits	A deployment-level label list can skip issues. An issue whose combined description and comments exceed the deployment’s ticket-size limit is skipped; the current default limit is 100 KiB.

Do not add updated or other time-based filters to custom JQL, and do not add an ORDER BY clause. Those expressions conflict with the connector’s polling and pagination logic.

Prerequisites

Identify the Jira site Base URL, such as https://<JIRA_SITE>.atlassian.net for Jira Cloud or the root URL of Jira Server/Data Center.
For Jira Cloud, create an API token for a user that can browse every project and issue in scope. Keep that user’s email available.
For Jira Server or Data Center, create a Personal Access Token for a user with the required browse access.
If using a scoped Jira Cloud token, keep the normal site Base URL and enable Using scoped token in the connector form. OpenCore resolves the site’s Cloud ID and sends API requests through Atlassian’s scoped API host.
For Auto Sync Permissions, the token also needs access to project permission schemes, project roles, users, groups, and group membership.

Credentials

Jira deployment	OpenCore credential values	Authentication behavior
Jira Cloud	`jira_user_email: <JIRA_USER_EMAIL>`, `jira_api_token: <JIRA_API_TOKEN>`	When the email field is present, OpenCore uses email-and-token basic authentication with Jira REST API v3.
Jira Cloud with scoped token	`jira_user_email: <JIRA_USER_EMAIL>`, `jira_api_token: <JIRA_SCOPED_TOKEN>`	Use the Cloud credential fields and also enable Using scoped token on the connector.
Jira Server or Data Center	`jira_api_token: <JIRA_PERSONAL_ACCESS_TOKEN>`	Leave Jira User Email blank. OpenCore omits that field and uses token authentication with Jira REST API v2.

The Base URL and scope settings belong to the connector, not the credential. Do not paste a project URL into the Base URL field.

Configure in OpenCore

In the Admin panel, open Connectors, select Jira, and create the credential for your Jira deployment.
Enter the Jira root Base URL. OpenCore removes a trailing slash before building API and issue links.
Enable Using scoped token only for a scoped Jira Cloud token.
Under How Should We Index Your Jira?, choose Everything, Project, or JQL Query. For Project, enter only the project key. For JQL Query, omit time filters and ORDER BY.
Optionally add comment-author email addresses to Comment Email Blacklist. Matching is case-sensitive and exact, depends on Jira returning comment.author.emailAddress, and is not a reliable privacy boundary. Verify each intended author after indexing.
Choose the document-access mode, set refresh and cleanup options, create the connector, and run the first indexing attempt.

Permissions

The credential determines which issues OpenCore can retrieve. Without Auto Sync Permissions, Jira access is not re-evaluated when a user searches: use OpenCore Private groups for restricted content, or Public only when every OpenCore account may search every indexed issue.

When Auto Sync Permissions is available and selected, OpenCore reads each project’s BROWSE_PROJECTS permission scheme and applies the resolved project access to every issue from that project. It recognizes anyone, direct users and groups, and actors in project roles. Jira groups and their member emails are synchronized separately.

applicationRole is currently treated as OpenCore Public as soon as that holder type is present. OpenCore does not synchronize the licensed Jira users behind that role, so every OpenCore account may search the project’s indexed issues, including accounts without a Jira license. If that is too broad, do not use Auto Sync for the connector; choose OpenCore Private groups and narrow the project or JQL scope instead.

This is project-level static permission resolution. The connector does not independently evaluate issue security levels, and dynamic holders such as reporter or assignee are not converted into per-issue ACLs. Unsupported or dynamic-only holders can resolve to empty private access. Test representative restricted projects before relying on synchronized access.

Verify

Validate the credential. For Everything, validation lists projects; for Project, it opens that project; for custom JQL, it executes a limited search.
Run an indexing attempt and search for one issue description and one comment in scope.
Confirm an issue outside the selected project or custom JQL is absent.
Use a target comment whose Jira API response exposes comment.author.emailAddress with the same case as the configured entry, then confirm that comment is absent. Also test a case mismatch or an author without a returned email and confirm the comment remains indexed. Confirm attachment-only text is not searchable.
Open a result link and confirm it uses the configured Base URL and /browse/<ISSUE_KEY>.
If using Auto Sync Permissions, test anyone, applicationRole, directly assigned, group-assigned, project-role, and issue-security cases. For applicationRole, include an OpenCore account without a Jira license and confirm whether the Public mapping is acceptable.

Troubleshooting

Symptom	What to check
Validation returns 401	Replace an expired or invalid API token or Personal Access Token, and confirm the Cloud email matches the token owner.
Validation returns 403	Grant the credential browse access for the selected project or JQL. Permission sync requires additional access to schemes, roles, users, and groups.
Project validation says the project does not exist	Check the exact project key and confirm the credential can see it.
Custom JQL is rejected or polling misses issues	Remove time-based predicates and `ORDER BY`; OpenCore adds its own `updated` range.
A targeted comment remains despite the blacklist	Confirm Jira returned `comment.author.emailAddress` and that it is a case-sensitive exact match. Missing emails and case differences do not filter the comment; use OpenCore access controls and connector scope rather than this field as a privacy boundary.
An issue is missing	Check the project or JQL scope, deployment label-skip configuration, the ticket-size limit, and issue browse permission.
Attachment text is missing	This is expected; the Jira connector does not fetch attachments.
Auto Sync access is too broad or too narrow	An `applicationRole` holder makes the project Public to all OpenCore accounts, including accounts without a Jira license. Issue security and dynamic holders are not resolved as per-issue ACLs. If either mapping is unsuitable, use Private groups and a narrower connector scope instead of Auto Sync.
Validation reports rate limiting	Wait for the Jira limit window to recover, then validate or index again.