> For the complete documentation index, see [llms.txt](https://integrations.drivetrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.drivetrain.ai/integration-guide/readme/others/integrating-with-jira.md).

# Integrating with Jira

Connect Jira to Drivetrain and sync project and issue data into operational models. Covers the Jira user permissions, API token, and submitting credentials in Drivetrain.

Drivetrain connects to Jira with the email address and API token of a Jira user (Jira Cloud), or a username and password (self-hosted Jira). You submit them in Drivetrain and your Drivetrain team finishes the setup.

### Before you start <a href="#prerequisites" id="prerequisites"></a>

1. **Admin** access in Drivetrain.
2. A Jira user that can read the data you want in Drivetrain. It needs these permissions:

| Entities                                                                                        | Roles & Permissions                                       |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| <p>Projects<br>Issues<br>Related entities like versions, components, and boards</p>             | **Administer Projects** or **Browse Projects** permission |
| <p>Project roles<br>Project role actors</p>                                                     | **Administer Projects** permission                        |
| <p>Users<br>Groups</p>                                                                          | **Browse users and groups** global permission             |
| Entities related to Jira Service Management (formerly Jira Service Desk)                        | **Administrators** or **Service Desk Team** project role  |
| <p>Permission and issue security schemes<br>Related entities<br>Webhooks (for registration)</p> | **Administer Jira** global permission                     |

### Jira setup <a href="#jira-setup" id="jira-setup"></a>

#### Jira Cloud: create an API token <a href="#method-1-basic" id="method-1-basic"></a>

1. Log in to <https://id.atlassian.com/manage-profile/security/api-tokens> as the Jira user above.
2. Click **Create API token**. Don't use **Create API token with scopes**: scoped tokens don't work with your Jira site URL.
3. Name the token and choose an expiration date (1 to 365 days).
4. Click **Create**, then **Copy to clipboard**, and store the token securely.

You'll also need the user's **email address** and your **Jira site URL** (for example, `https://yourcompany.atlassian.net`).

{% hint style="warning" %}
The connection stops working when the token expires. Create a new token before then and send it to your Drivetrain team.
{% endhint %}

#### Self-hosted Jira

You'll need the Jira user's **username** and **password**, your Jira **host** and the **port** number.

### Connect in Drivetrain

1. On the **Data** page, click **+** next to **Data** (or **Add data source** if nothing is connected yet).
2. In **Connect a data source**, select **Jira**. It's a premium integration: click **Request access**.
3. Under **Fields**, click **Add field** for each value: email, API token and Jira site URL (Jira Cloud), or username, password, host and port (self-hosted).
4. Click **Submit credentials**.

The connection shows **Credentials submitted** until your Drivetrain team finishes the setup.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* **Submit credentials does nothing:** add at least one field with a value.
* **"This connector is currently being set up. Please try again once it finishes."** Your Drivetrain team is activating the connection. Wait until it finishes before you submit again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://integrations.drivetrain.ai/integration-guide/readme/others/integrating-with-jira.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
