> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-connect-workflows-with/jira.md).

# Jira

### Overview

Workflows work with your Jira Cloud projects in two ways:

* **From a card:** when a card is created, Birdie finds the customer evidence behind it and links a report to the card.
* **From the opportunities:** every week Birdie checks whether an open card already covers each opportunity customers are raising. If it does, Birdie **comments** on that card with what is new. If it does not, Birdie **proposes a new card** (created only after someone approves it, unless you choose otherwise).

### What Birdie will do

| Action                                                       | Where                                                               |
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
| Search and read cards (title, description, status, comments) | Only the project and issue types you configure                      |
| Add a comment (marked "Birdie VoC · new evidence")           | On a card that already covers an opportunity                        |
| Create a card                                                | Only in the configured project, using the first issue type you list |
| Add a link to a Birdie report                                | On the card that triggered the workflow                             |

Birdie never deletes, edits or transitions your existing cards.

### Requirements

* Jira **Cloud** (your site looks like `https://your-company.atlassian.net`).
* An Atlassian account for Birdie. We recommend a dedicated one, for example `birdie@your-company.com`, so comments and cards appear as coming from Birdie.
* A Jira administrator to give that account access to the project.

### Setup

{% stepper %}
{% step %}

### Give the account access to the project

In the project's **Project settings → Access** (or your permission scheme), make sure the Birdie account has:

* **Browse projects**
* **Add comments**
* **Create issues**
* **Link issues** (only for the "from a card" workflow)

Give it access to the project the workflow uses and nothing more.
{% endstep %}

{% step %}

### Create an API token

* Sign in to Atlassian **as the Birdie account**.
* Go to [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
* Click **Create API token** (the standard token, not the token with scopes), name it `Birdie Workflows` and choose an expiry date.
* Copy the token now. Atlassian shows it only once.

Atlassian API tokens expire. Note the date and create a replacement before it passes.
{% endstep %}

{% step %}

### Note what Birdie needs

* **Jira site URL**, for example `https://your-company.atlassian.net`
* **Account email** of the Birdie account
* **API token** from the previous step
* **Project key** (the prefix of your cards, for example `CX` in `CX-123`)
* **Issue types** the workflow should look at, for example `Story, Task`. The first one is used for new cards.
  {% endstep %}

{% step %}

### Optional: send "card created" events to Birdie

Only the "from a card" workflow needs this. A Jira administrator creates a webhook in **Settings → System → WebHooks**, with the URL Birdie gives you for the workflow and the event **Issue → created** (restrict it with a JQL filter such as `project = CX`).
{% endstep %}
{% endstepper %}

### Connect to Birdie

When you set up the workflow, choose **+ New credential** in the Jira field and enter the site URL, email and API token. Birdie stores them encrypted and never shows the token again.

If you prefer not to type it into Birdie, [share it securely](https://onetimesecret.com/en/) with your Birdie contact.

### Revoke or rotate

* Revoke the token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens). Workflows stop acting on Jira immediately.
* To rotate, create a new token and update the credential in Birdie. The workflow keeps its history.
* Removing the Birdie account from the project also stops all access.


---

# 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://ask.birdie.ai/integrations-and-data-ingestion/how-to-connect-workflows-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.
