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

# Jira Toolset

> Issue tracking and project management integration for AI agents

<div className="max-w-2xl mx-auto mt-12">
  <div className="p-6 border border-gray-200 dark:border-gray-700 rounded-lg bg-blue-50 dark:bg-gray-800">
    <div className="flex items-center mb-4">
      <img src="https://mintcdn.com/pipeshub/8k-iBPRh1yJZHQe1/logo/jira.png?fit=max&auto=format&n=8k-iBPRh1yJZHQe1&q=85&s=4c85f433a48529979a9483588af17bfc" alt="Jira Logo" className="w-8 h-8 mr-3 object-contain flex-shrink-0" width="567" height="567" data-path="logo/jira.png" />

      <h2 className="text-2xl font-semibold m-0">Jira Toolset</h2>
    </div>

    <p className="text-lg text-gray-700 dark:text-gray-300 mb-4">Issue tracking, project management, and team collaboration</p>

    <div className="flex items-center gap-2">
      <span className="px-3 py-1 bg-green-100 dark:bg-green-900 text-green-800 dark:text-green-200 rounded-full text-sm font-medium">
        Ready
      </span>

      <span className="px-3 py-1 bg-purple-100 dark:bg-purple-900 text-purple-800 dark:text-purple-200 rounded-full text-sm font-medium">
        Atlassian
      </span>
    </div>
  </div>
</div>

## Overview

The Jira toolset enables AI agents to interact with your Jira workspace. Agents can create issues, search tickets, add comments, update issues, and more. This toolset is ideal for automating project management workflows and integrating Jira into conversational AI experiences.

### Key Capabilities

* **Create and manage issues** - Create new tickets, update existing ones, change status
* **Search with JQL** - Find issues using Jira Query Language
* **Comment management** - Add and retrieve comments on issues
* **Project operations** - List projects, get project metadata
* **User operations** - Search users, get current user info

***

## Available Tools

| Tool                   | Description                                                             | Type    |
| ---------------------- | ----------------------------------------------------------------------- | ------- |
| `create_issue`         | Create a new Jira issue                                                 | Action  |
| `update_issue`         | Update an existing issue (summary, description, status, assignee, etc.) | Action  |
| `get_issue`            | Get details of a specific issue                                         | Search  |
| `get_issues`           | Get issues from a project                                               | Search  |
| `search_issues`        | Search issues using JQL queries                                         | Search  |
| `add_comment`          | Add a comment to an issue                                               | Action  |
| `get_comments`         | Get comments for an issue                                               | Search  |
| `get_projects`         | Get all Jira projects                                                   | Search  |
| `get_project`          | Get details of a specific project                                       | Search  |
| `get_project_metadata` | Get project metadata (issue types, components)                          | Search  |
| `search_users`         | Search users by name or email                                           | Search  |
| `get_current_user`     | Get current authenticated user info                                     | Search  |
| `validate_connection`  | Validate Jira connection status                                         | Utility |
| `convert_text_to_adf`  | Convert plain text to Atlassian Document Format                         | Utility |

***

## Configuration Guide

The Jira toolset supports **two authentication methods**. In both, an admin first configures the shared instance under **Workspace Settings → Actions**, then each user connects their personal account under **Your actions**.

| Method              | Best for                                                                                                                      |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **OAuth 2.0 (3LO)** | Multi-user / org-wide rollouts. One Atlassian app, per-user consent via OAuth popup.                                          |
| **API Token**       | When you cannot register an Atlassian OAuth app, or you want per-user tokens. Each user provides their own Email + API Token. |

<Tabs>
  <Tab title="OAuth 2.0">
    #### Step 1: Access the Atlassian Developer Console

    1. Go to [developer.atlassian.com/console/myapps/](https://developer.atlassian.com/console/myapps/) and sign in with your Atlassian account (must have admin access to your Jira workspace).

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/OV7q-p-MhGhaahZJ/images/connectors/jira/create_new_app.png?fit=max&auto=format&n=OV7q-p-MhGhaahZJ&q=85&s=23a886c299ada61082de1fade33ac981" alt="Atlassian Developer Console" className="block mx-auto w-11/12" width="1576" height="672" data-path="images/connectors/jira/create_new_app.png" />
    </div>

    #### Step 2: Create an OAuth 2.0 integration

    1. Click **Create** in the top-right corner.
    2. Select **OAuth 2.0 integration**.
    3. Enter a name (e.g., `PipesHub Jira Toolset`) and accept the developer terms.
    4. Click **Create**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/CB4tzc9xyu8XG-4X/images/toolsets/jira/create_new_app_form.png?fit=max&auto=format&n=CB4tzc9xyu8XG-4X&q=85&s=34ce7d90b44a8a188987b5f1aee7c01c" alt="Create OAuth Integration" className="block mx-auto w-11/12" width="764" height="742" data-path="images/toolsets/jira/create_new_app_form.png" />
    </div>

    #### Step 3: Get the Redirect URI from PipesHub

    Before configuring the Callback URL in Atlassian, copy the Redirect URI from PipesHub.

    1. In PipesHub, go to **Workspace Settings** → **Actions**.
    2. Find **Jira** in the list and click **+ Setup** for a new instance.
    3. Copy the **Redirect URI** shown in the dialog.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/pipeshub-config.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=83aa2f9eccedcd46499406a9bbc90e32" alt="PipesHub Configure Jira toolset — copy the Redirect URI" className="block mx-auto w-11/12" width="1904" height="901" data-path="images/toolsets/jira/pipeshub-config.png" />
    </div>

    #### Step 4: Configure the Callback URL in Atlassian

    1. In Atlassian Developer Console, click **Authorization** in the left sidebar.
    2. Click **Add** under **OAuth 2.0 (3LO)**.
    3. Paste the Redirect URI from PipesHub into the **Callback URL** field.
    4. Click **Save changes**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/CB4tzc9xyu8XG-4X/images/toolsets/jira/add_callback_url.png?fit=max&auto=format&n=CB4tzc9xyu8XG-4X&q=85&s=714b67b673a4962650b51f916d639407" alt="Add Callback URL" className="block mx-auto w-11/12" width="1909" height="880" data-path="images/toolsets/jira/add_callback_url.png" />
    </div>

    <Warning>
      The Callback URL must match exactly. Any mismatch — trailing slash, protocol, casing — will cause authentication to fail.
    </Warning>

    #### Step 5: Add required scopes

    1. In the left sidebar, click **Permissions**.
    2. Add scopes for both **User identity API** and **Jira API**.

    **User Identity API**

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

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/OV7q-p-MhGhaahZJ/images/connectors/jira/user_identity_scopes.png?fit=max&auto=format&n=OV7q-p-MhGhaahZJ&q=85&s=b46b5ec0ff25d77bd2f7ccd17d0d35bf" alt="User Identity API Scopes" className="block mx-auto w-11/12" width="1818" height="767" data-path="images/connectors/jira/user_identity_scopes.png" />
    </div>

    **Jira API — Classic scopes**

    | Scope             | Description                            |
    | ----------------- | -------------------------------------- |
    | `read:jira-work`  | Read Jira project and issue data       |
    | `write:jira-work` | Create and update issues, add comments |
    | `read:jira-user`  | Read user information                  |

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/CB4tzc9xyu8XG-4X/images/toolsets/jira/classic_scopes.png?fit=max&auto=format&n=CB4tzc9xyu8XG-4X&q=85&s=e78ac523c385a1957a4ea02855b52d21" alt="Jira Classic Scopes" className="block mx-auto w-11/12" width="1914" height="909" data-path="images/toolsets/jira/classic_scopes.png" />
    </div>

    **Jira API — Granular scopes**

    | 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                         |
    | `read:application-role:jira` | Read application roles                  |
    | `read:project-role:jira`     | Read project roles and role assignments |

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/OV7q-p-MhGhaahZJ/images/connectors/jira/granular_scopes.png?fit=max&auto=format&n=OV7q-p-MhGhaahZJ&q=85&s=33bbb4e35a1138bff5dd385d7df83f89" alt="Jira Granular Scopes" className="block mx-auto w-11/12" width="1835" height="842" data-path="images/connectors/jira/granular_scopes.png" />
    </div>

    #### Step 6: Copy Client ID and Client Secret

    1. In the left sidebar, click **Settings**.
    2. Under **Authentication details**, copy:
       * **Client ID** — used as **Client ID** in PipesHub.
       * **Secret** — used as **Client Secret** in PipesHub.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/28FaxV16yHh2aGik/images/connectors/jira/auth_creds.png?fit=max&auto=format&n=28FaxV16yHh2aGik&q=85&s=463a4ea4d3751adbb62c904f6d50db07" alt="Copy OAuth Credentials" className="block mx-auto w-11/12" width="1594" height="862" data-path="images/connectors/jira/auth_creds.png" />
    </div>

    #### Step 7: Admin — configure the toolset in Actions

    1. In PipesHub, return to **Workspace Settings** → **Actions**, find **Jira**, and reopen the setup dialog.
    2. Confirm the **Redirect URI** matches the Callback URL you saved in Atlassian in Step 4.
    3. Enter:
       * **Instance Name** (e.g., `Jira Production`)
       * **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)
    4. Click **Create**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/enter-credentials.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=845f511d60e7a9a0beadf5cd1bb8fc34" alt="Enter Client ID, Client Secret, and Atlassian Site URL in PipesHub" className="block mx-auto w-11/12" width="1903" height="911" data-path="images/toolsets/jira/enter-credentials.png" />
    </div>

    <Info>
      **Atlassian Site URL** is an org-level field — it points to the specific Jira Cloud site this toolset instance will act on. Client ID and Client Secret are the org's OAuth app credentials. Per-user tokens are issued by Atlassian when each user authenticates in the next step.
    </Info>

    #### Step 8: Authenticate the toolset

    Authentication uses the same OAuth flow in either location:

    * **Admins** can authenticate the shared instance directly under **Workspace Settings → Actions**.
    * **Users** can authenticate their own personal instance under **Your actions** (in the **Personal** section of the sidebar).

    1. On the Jira tile (in **Actions** or **Your actions**), click **Authenticate with OAuth**.
    2. A popup opens to Atlassian's authorization page — select your Jira site from the dropdown.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/oauth_page_choose_app.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=8da0a12fcd8b50f34eddbd97b1908a35" alt="Select Jira Site" className="block mx-auto w-11/12" width="1900" height="898" data-path="images/toolsets/jira/oauth_page_choose_app.png" />
    </div>

    3. Review the permissions and click **Accept**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/oauth_page_accept.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=9ec67f857499531eb89c188f0b9b9fb0" alt="Accept Permissions" className="block mx-auto w-11/12" width="1919" height="914" data-path="images/toolsets/jira/oauth_page_accept.png" />
    </div>

    4. The popup closes and the Jira tile shows **Authenticated** status.

    <Warning>
      **Authorize using the same email as your PipesHub account.** Using a different email causes permission issues on the PipesHub platform.
    </Warning>

    #### Step 9: Add Jira to an agent

    1. Go to the **Home** page.
    2. Next to **Agents**, click **+** to create a new agent.
    3. Give the agent a name, drag the **Jira** toolset onto the canvas, connect it to the **Agent Core** node with your model and chat input/output, then create the agent.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/create_agent.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=c46578e5a886fb568c10ad11c6a4df84" alt="Agent builder with Jira toolset connected" className="block mx-auto w-11/12" width="1919" height="911" data-path="images/toolsets/jira/create_agent.png" />
    </div>
  </Tab>

  <Tab title="API Token">
    The API Token method has a clear org/user split:

    * **Admin** configures only the **Atlassian Site URL** under **Actions** (org-level field).
    * **Each user** then opens **Your actions** and enters their own **Email** + **API Token** to authenticate the toolset for themselves.

    This is different from the connector — here every user that wants to use the toolset needs their own API token, since each agent action runs under that user's identity.

    #### Step 1: Each user generates an API token in Atlassian

    Each user that will use the toolset must generate their own API token.

    1. Sign in to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
    2. Click **Create API token**, set a meaningful label (e.g., `PipesHub Jira Toolset`) and an expiry if you want, then click **Create**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/api_token_create.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=e83f452bbff5fb30df7d1de5eebdd0ba" alt="Atlassian Create API token dialog" className="block mx-auto w-11/12" width="1919" height="863" data-path="images/toolsets/jira/api_token_create.png" />
    </div>

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

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/api_token_copy.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=85b58e23f168b42d303539df03feef4e" alt="Copy the API token — shown once" className="block mx-auto w-11/12" width="1917" height="869" data-path="images/toolsets/jira/api_token_copy.png" />
    </div>

    <Warning>
      The API token is shown only once. If you close the dialog without copying it, create a new token.
    </Warning>

    #### Step 2: Admin — configure the toolset instance in Actions

    The admin sets up only the **org-level** field (the Atlassian Site URL). No credentials are entered here — those come from each user in the next step.

    1. In PipesHub, go to **Workspace Settings** → **Actions**.
    2. Find **Jira** and click **+ Setup** for a new instance.
    3. In the dialog, choose **API Token** as the authentication method, then enter only:
       * **Instance Name** (e.g., `Jira Production`)
       * **Atlassian Site URL** — your Jira site URL (e.g., `https://your-domain.atlassian.net`; no trailing slash)
    4. Click **Create**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/api_token_actions_admin.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=9eb4b0cff32fbf4a360b2d671e61dd5b" alt="Admin Actions dialog — API Token method shows only Instance Name and Atlassian Site URL" className="block mx-auto w-11/12" width="1917" height="900" data-path="images/toolsets/jira/api_token_actions_admin.png" />
    </div>

    <Info>
      Clicking the instance settings later reopens this drawer where you can change **Instance Name** and **Atlassian Site URL**. A button below opens **Your actions** so each user can add their own credentials.
    </Info>

    #### Step 3: Each user — add Email + API Token in Your actions

    Each user that wants to use the toolset must complete this step with their own credentials.

    1. In PipesHub, open **Your actions** (in the **Personal** section of the sidebar).
    2. Find the Jira instance and open it.
    3. Enter:
       * **Email** — your Atlassian account email (the account that created the API token in Step 1)
       * **API Token** — the token you copied in Step 1
    4. Click **Save credentials**.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/api_token_your_actions.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=a4edb67d307debe1c045c767b2e27a32" alt="Your actions — enter Email and API Token" className="block mx-auto w-11/12" width="1917" height="908" data-path="images/toolsets/jira/api_token_your_actions.png" />
    </div>

    The Jira tile in **Your actions** now shows **Authenticated**. The toolset is connected for this user only — every other user must repeat Step 3 with their own email + token.

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

    #### Step 4: Add Jira to an agent

    1. Go to the **Home** page.
    2. Next to **Agents**, click **+** to create a new agent.
    3. Give the agent a name, drag the **Jira** toolset onto the canvas, connect it to the **Agent Core** node with your model and chat input/output, then create the agent.

    <div className="text-center">
      <img src="https://mintcdn.com/pipeshub/A_XbndOBA0469cd0/images/toolsets/jira/create_agent.png?fit=max&auto=format&n=A_XbndOBA0469cd0&q=85&s=c46578e5a886fb568c10ad11c6a4df84" alt="Agent builder with Jira toolset connected" className="block mx-auto w-11/12" width="1919" height="911" data-path="images/toolsets/jira/create_agent.png" />
    </div>
  </Tab>
</Tabs>

***

## FAQ

<AccordionGroup>
  <Accordion title="Which authentication method should I choose?">
    |                     | OAuth 2.0                                    | API Token                                     |
    | ------------------- | -------------------------------------------- | --------------------------------------------- |
    | **Best for**        | Multi-user / org-wide rollouts               | Cases where OAuth app registration is blocked |
    | **Org-level setup** | Client ID, Client Secret, Atlassian Site URL | Atlassian Site URL only                       |
    | **Per-user setup**  | OAuth popup (one click)                      | Each user pastes Email + API Token            |
    | **Prerequisites**   | Atlassian Developer Console admin access     | Any Atlassian account                         |

    Choose **OAuth** for the simplest per-user experience. Choose **API Token** when you cannot register an Atlassian OAuth app or when each user wants to manage their own token (for example, to set tighter scopes or expiry).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

<Info>
  When searching issues, always include a time range (e.g., "from the last 30 days" or "updated this week") to get accurate results.
</Info>

***

## Usage Tips

**How do I create an issue?**\
Simply ask your agent to "create a Jira ticket" and provide the project key, title, and issue type (Task, Bug, or Story). You can also specify assignee, priority, and labels.

**How do I search for issues?**\
Ask to "find Jira issues" with specific criteria. The agent will use JQL syntax automatically. For example: "show me all in-progress issues in project PA from the last week"

**How do I assign issues?**\
You can assign by name (e.g., "assign to John Smith") or by email. The agent will look up the correct account ID automatically.

**How do I update issue status?**\
Ask to "move issue PA-123 to In Progress" or "mark PA-456 as Done". Common statuses include "To Do", "In Progress", and "Done".