Jira
Jira
By the end of this guide, you will have your Jira project indexed into a semantic collection that your AI agent can query in plain English — finding relevant tickets by meaning, not just keywords.
Prerequisites
- Indexed installed and workspace initialized (
indexed config init; see Quick Start) - A Jira Cloud or Jira Server/Data Center instance
- Credentials for your deployment type (step 1)
Cloud vs Server/Data Center
Use the same command for both: indexed index create jira. Indexed picks the connector from the base URL: hosts ending in atlassian.net are treated as Jira Cloud; everything else is Jira Server/Data Center.
Full flags: Index commands — indexed index create jira (indexed index create jira --help). Environment variables: Config commands — Connector credentials.
Credentials
Cloud vs. Server/Data Center auth
Jira Cloud uses an Atlassian API token plus the email for the account that owns the token. Set ATLASSIAN_EMAIL and ATLASSIAN_TOKEN, or pass --email and --token for that run.
Jira Server/Data Center can use a bearer or personal access token (JIRA_TOKEN), or username and password (JIRA_LOGIN and JIRA_PASSWORD). No Atlassian email is used.
- Go to https://id.atlassian.com/manage-profile/security/api-tokens
- Click Create API token
- Give it a label (e.g., "Indexed CLI")
- Copy the token
Set both variables in your shell or .env file:
export ATLASSIAN_EMAIL=your-email@company.com
export ATLASSIAN_TOKEN=your_api_token_hereToken (typical): create a Personal Access Token under your Jira profile, then:
export JIRA_TOKEN=your_personal_access_tokenUsername and password (when your site uses basic auth instead):
export JIRA_LOGIN=your_username
export JIRA_PASSWORD=your_passwordKeep tokens out of version control
Store credentials in a .env file and add it to .gitignore. Never put API tokens in config.toml or commit them to a repository.
Index Your Tickets
Minimal example (collection name, site URL, JQL):
indexed index create jira -c eng-tickets -u https://company.atlassian.net -q "project = ENG"Pick a JQL query that targets the tickets you care about; narrow or widen as needed:
indexed index create jira \
-c eng-tickets \
-u https://company.atlassian.net \
-q "project = ENG AND created >= -90d"Indexing collection 'eng-tickets'...
Fetched 142 issues from Jira
Parsed 142 documents
Created 318 chunks
Generated embeddings
✓ Collection 'eng-tickets' created (318 chunks, 12.4 MB)Verify the collection looks right:
indexed index inspect eng-ticketsCollection: eng-tickets
Type: jira
Source: https://company.atlassian.net
Query: project = ENG AND created >= -90d
Documents: 142
Chunks: 318
Size: 12.4 MB
Created: 2026-04-06 14:30:22Search Your Backlog
Test the collection from the CLI before connecting an AI agent:
indexed index search "auth timeout issues" -c eng-ticketsResults for 'auth timeout issues' (top 5):
1. [eng-tickets] ENG-1847: SSO refresh token expiration handling (chunk 1/2)
Score: 0.84
...Users experience session drops when the SSO refresh token expires
during long-running operations. The fix in ENG-1848 added proactive
token renewal...
2. [eng-tickets] ENG-2103: Login timeout after IdP migration (chunk 1/3)
Score: 0.78
...After migrating to the new identity provider, login requests time
out for users on VPN. Workaround is to increase the IdP response
timeout to 30s...The query "auth timeout issues" returned tickets about SSO token expiration and IdP migration — neither of which matches those exact words. That's semantic search in practice.
Common JQL Patterns
Use these as starting points for -q / --jql (replace ENG with your project key):
| Goal | JQL |
|---|---|
| Project slice | project = ENG |
| Recent tickets | project = ENG AND created >= -90d |
| Open issues | project = ENG AND status != Done |
| Bugs only | project = ENG AND type = Bug |
| Exclude sub-tasks | project = ENG AND type != Sub-task |
Keep the Index Current
Jira moves fast. Pull in new and modified tickets with an incremental update:
indexed index update eng-ticketsFor hands-free updates, add a cron job:
# Update every 4 hours
0 */4 * * * /path/to/indexed index update eng-ticketsTroubleshooting
Authentication errors for Cloud — set both ATLASSIAN_EMAIL and ATLASSIAN_TOKEN. The email must match the Atlassian account that generated the token.
Authentication errors for Server/DC — confirm JIRA_TOKEN, or JIRA_LOGIN and JIRA_PASSWORD, match what your Jira instance expects.
Empty results — run your JQL query directly in Jira's issue search to confirm it returns results. Also double-check that the URL includes the protocol (https://).
Rate limiting — Indexed retries automatically when it hits Jira rate limits. For large projects (1,000+ tickets), narrow your JQL query to index in smaller batches.