> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyshift.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira Integration

> Connect your Jira instance to enable Annie to search issues, access ticket details, and leverage project information during incident investigation.

# Jira Integration

Jira integration enables Annie to access your issue tracker, allowing it to search tickets, retrieve issue details, and correlate incidents with existing bugs, tasks, and historical issues.

## Setup Guide

1. Go to the [Anyshift integrations page](https://app.anyshift.io/integrations)
2. Navigate to the Knowledge Base section
3. Select **Jira**
4. Click **Connect Jira**
5. Enter your **Jira Domain**, **Email**, and **API Token**
6. Click **Save**

### 1. Jira Domain

Enter your Atlassian domain (e.g., `yourcompany.atlassian.net`).

This is the URL you use to access Jira Cloud. For example, if you access Jira at `https://acme.atlassian.net`, enter `acme.atlassian.net`.

### 2. Email

Enter the email address associated with your Atlassian account (e.g., `user@company.com`).

### 3. API Token

Anyshift supports both **scoped** and **classic** Atlassian API tokens. We recommend scoped tokens for least-privilege access.

No admin configuration is required — any Atlassian user can create a token and connect their Jira instance.

#### Option A: Scoped API Token (Recommended)

Generate a scoped API token with Jira read permissions:

1. Go to [Atlassian API Token Management](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Select **Scoped** token type
4. Enter a label (e.g., "Anyshift Integration")
5. Grant the following scopes:
   * `read:jira-work` - Read Jira issues and projects
   * `read:jira-user` - Read user information
   * `read:servicedesk-request` - Read service desk requests
   * `read:me` - Read your profile information
   * `read:account` - Read account information
6. Click **Create**
7. Copy the token and paste it into Anyshift

#### Option B: Classic API Token

If you prefer a simpler setup, you can use a classic (non-scoped) API token. Classic tokens inherit all permissions of the Atlassian account.

1. Go to [Atlassian API Token Management](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **Create API token**
3. Select **Classic** token type
4. Enter a label (e.g., "Anyshift Integration")
5. Click **Create**
6. Copy the token and paste it into Anyshift

For more details, see [Atlassian's API Token documentation](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/).

Keep your API token secure and do not share it publicly.

## Required Permissions

Annie performs **read-only** operations on your Jira instance. Your API Token grants access based on your Atlassian account permissions.

Your account needs access to:

* View projects
* View issues and their details
* Search issues using JQL

Annie does not create, modify, or delete any issues, comments, or other content in your Jira instance.

## How It Works

Once connected, Annie can leverage your Jira instance during:

* **Incident Investigation**: When analyzing an incident, Annie searches for related issues, bugs, and historical tickets to find relevant context and past resolutions
* **Question Answering**: When you ask about specific tickets or projects, Annie retrieves the details directly from Jira
* **Correlation**: Annie can correlate alerts and incidents with existing Jira tickets to identify known issues

### Example Use Cases

* "Search Jira for authentication issues from the last week"
* "Get details on ticket INFRA-1234"
* "Find all high-priority bugs in the Platform project"
* "What Jira tickets are related to Redis connection issues?"

Annie will search your Jira instance using JQL (Jira Query Language) and cite relevant issues in its responses.

### JQL Query Examples

Annie can construct JQL queries automatically based on your questions:

| Question                     | JQL Query                                             |
| ---------------------------- | ----------------------------------------------------- |
| "Recent bugs"                | `type = Bug AND created >= -7d ORDER BY created DESC` |
| "Open high priority issues"  | `priority = High AND status != Done`                  |
| "Authentication issues"      | `text ~ "authentication" OR summary ~ "auth"`         |
| "Issues in Platform project" | `project = PLATFORM ORDER BY updated DESC`            |

## Supported Features

Annie can access the following Jira data:

**Issues**

* Search issues using JQL
* Get full issue details (summary, description, status, priority, assignee, etc.)
* View available status transitions

**Projects**

* List all accessible projects
* Get project details and metadata

**Metadata**

* Get available issue types for a project
* Get custom field definitions

## Project Scoping

You can optionally restrict which Jira projects Annie can access by specifying **Allowed Projects** when configuring credentials.

Enter a comma-separated list of Jira project keys (e.g., `CSGSRE,SRESD,CTXSRESD`). When configured:

* **Searches** are automatically scoped to the specified projects
* **Direct issue access** is restricted — Annie cannot fetch issues from projects not in the list
* **Project listings** only show the allowed projects

Leave the field empty to allow access to all projects the service account can see.

This is useful when a service account has broad access but you want Annie to focus on specific projects. For stronger isolation, you can also configure project-level permissions on the Atlassian service account itself.

## Security

* API tokens are encrypted at rest using AWS KMS
* Anyshift only reads from your Jira instance (no write operations)
* All communication uses HTTPS/TLS encryption
* Credentials are validated directly against the Jira REST API

## Troubleshooting

### "401 Unauthorized" or "Invalid credentials" error

This is usually caused by one of the following:

1. **Token missing required scopes** (scoped tokens only): Ensure your scoped token has the `read:jira-work`, `read:jira-user`, `read:servicedesk-request`, `read:me`, and `read:account` scopes.

2. **Email/token mismatch**: Verify your email matches your Atlassian account email exactly.

3. **Expired or revoked token**: Generate a new API token from your [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens).

### "No issues found" when searching

* Verify your account has permission to view the projects being searched
* Check that the JQL query syntax is valid
* Ensure issues exist matching your search criteria

### Connection timeout

* Verify your Jira domain is correct (e.g., `yourcompany.atlassian.net`)
* Check that your Atlassian instance is accessible

Ready to get started? [Configure Jira Integration](https://app.anyshift.io/integrations)