> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/integrations/issue-tracking/jira.md).

# Jira

The Jira integration connects codev to your Atlassian Jira site so that the work items referenced in your commits are visible throughout your delivery pipeline — and, optionally, so that codev reports deployment and build status back to the matching Jira issues.

You configure it under **Settings > Organization > Integrations > Jira**. Only organization owners can manage it.

## What the Jira integration does

The integration works in two directions. Reading work items is enough for most teams; write-back is optional and needs the OAuth method.

| Capability                                                                                             | Supported | Needs                           |
| ------------------------------------------------------------------------------------------------------ | --------- | ------------------------------- |
| Read a Jira issue and show its summary, status, assignee, and a link                                   | ✅         | Basic Auth or OAuth             |
| Search issues with filters (project, status, assignee, type)                                           | ✅         | Basic Auth or OAuth             |
| Detect Jira issue keys in commit messages and surface them on builds, release candidates, and releases | ✅         | Basic Auth or OAuth             |
| Report deployments to Jira's **Deployments** panel                                                     | ✅         | OAuth + write-back enabled      |
| Report builds to Jira's **Builds** panel                                                               | ✅         | OAuth + write-back enabled      |
| Add a cumulative deployment-timeline comment to each referenced issue                                  | ✅         | OAuth + write-back enabled      |
| Create, edit, transition, or close issues                                                              | ❌         | Use Jira Automation (see below) |

codev never edits your issues directly. To move an issue's status when it is deployed, drive a **Jira Automation** rule from the deployment data codev writes back.

## Authentication methods

Jira offers two methods. They are independent — you can register one or both, and each can serve a different purpose.

| Method                       | What you provide                                 | What it powers                                                                                    |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Basic Auth (API Token)**   | Base URL, your Atlassian email, and an API token | Reading issues and searching — everything that displays and links work items.                     |
| **OAuth Client Credentials** | Base URL, Client ID, and Client Secret           | Writing deployment and build status back to Jira's DevOps panels and adding the timeline comment. |

{% hint style="info" %}
If both are registered, codev reads issues through **Basic Auth** and writes back through **OAuth**. If only OAuth is registered, it can also read issues, with the scope its DevOps app allows.
{% endhint %}

{% hint style="warning" %}
**Write-back is Atlassian Cloud only.** The OAuth method targets Jira Cloud sites (`*.atlassian.net`). Reading via Basic Auth works against any reachable Jira site that accepts an API token.
{% endhint %}

## You bring your own Jira

Unlike GitHub on the cloud instance, there is **no flxbl-managed Jira connection**. Jira is always something your organization connects itself — on both the cloud and self-hosted instances. Until you register a Jira integration, work items are not read and nothing is written back.

## Adding the integration

1. Go to **Settings > Organization > Integrations > Jira**.
2. Under **Add New Integration**, choose the **Authentication Method**.
3. Fill in the credentials:
   * **Basic Auth (API Token)** — your site **Base URL** (`https://your-domain.atlassian.net`), your Atlassian email as the **Username**, and an **API Token** created at *Atlassian Account Settings > Security > API tokens*.
   * **OAuth Client Credentials** — your site **Base URL**, and the **Client ID** and **Client Secret** of a Jira OAuth credential (see [Creating the OAuth credential](#creating-the-oauth-credential) below).
4. Set **Availability** to **Global** (optionally marking it the default for Jira) or to a **specific project**.
5. Click **Add Integration**.

Existing integrations are listed with their method, scope, default marker, and status, and can be edited or removed at any time.

<figure><img src="/files/vrjRAYqCa7a9jhBhJA02" alt="The Jira integration page with the Add New Integration form"><figcaption><p>Settings > Organization > Integrations > Jira — the <strong>Authentication Method</strong> selector switches between Basic Auth (base URL, Atlassian email, API token) and OAuth Client Credentials (base URL, Client ID, Client Secret).</p></figcaption></figure>

## Creating the OAuth credential

The OAuth Client Credentials method authenticates to Jira's DevOps APIs (Deployments and Builds), and the credential for those APIs is created by a Jira site admin — **not** in the Atlassian Developer Console.

1. In Jira, go to **Settings > Apps > OAuth credentials**.
2. Select **Create new credentials**.
3. Give it a name and a **Server base URL** (your codev instance URL), and grant the **Deployments** and **Builds** permissions.
4. Copy the generated **Client ID** and **Client Secret** into the **OAuth Client Credentials** fields on the codev Jira integration form, along with your site **Base URL**.

<figure><img src="/files/AdWJYjkL6CV7QWfIUrij" alt="The Jira OAuth credentials admin page with a credential granting Builds and Deployments permissions"><figcaption><p>Jira > Settings > Apps > OAuth credentials — create a credential with the Deployments and Builds permissions, then copy its Client ID and Secret into codev.</p></figcaption></figure>

## Scoping and precedence

Each integration is either **Global (all projects)** or scoped to a **specific project**, and a global integration can be marked the **default** for Jira. When codev needs Jira credentials for a project, it picks the most specific match:

1. A Jira integration scoped to **that project**
2. The integration marked **default** for Jira
3. A **global** Jira integration

## Showing work items

Once a read-capable integration is registered, codev extracts Jira issue keys from your commit messages (for example, `DP-123` or `[PROJ-456]`) and surfaces them where you plan and ship. For the full set of recognised commit-message formats — and a common pitfall, since an issue key in round parentheses is not detected — see [Work items](/flxbl/codev/ci-cd/work-items.md). Detected keys are surfaced:

* On a **release candidate**, under the **Work Items** tab, grouped by source with the Jira issues shown as clickable keys.
* In the **release request** flow, as *indicative work items*, so you can see which issues a release will deploy and whether the deployment is full or partial.

<figure><img src="/files/F2iGGjvyH04BnxUOVzC3" alt="Release candidates with detected Jira issue keys shown in the Work Items column"><figcaption><p>Detected Jira issue keys appear against each release candidate; click a key to open the issue in Jira.</p></figcaption></figure>

How keys are detected and linked is part of each project's configuration:

| Setting               | What it controls                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `jiraProjects`        | Limits work items to specific project keys, e.g. `["DP", "PROJ"]`.                                           |
| `baseUrl`             | The browse URL used to build issue links, e.g. `https://your-domain.atlassian.net/browse`.                   |
| `workItemRegexFilter` | A custom pattern for issue keys when the default `ABC-123` style does not fit, e.g. `(FGK\|FFK)-[0-9]{3,4}`. |

## Writing status back to Jira

Write-back is optional. It is active for a project only when **both** conditions are met:

* An **OAuth Client Credentials** integration is registered, and
* Write-back is **enabled** in the project's configuration.

<figure><img src="/files/zWXiSd3UnbwsUZzf2S3y" alt="The project configuration editor with Jira write-back enabled"><figcaption><p>Enable write-back in the project configuration — <code>jiraWriteBack.enabled</code> set to <code>true</code>.</p></figcaption></figure>

When active, codev reports to Jira as your pipeline runs:

| Event                                   | What appears in Jira                                                                                                                                                  |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A release is deployed to an environment | A deployment entry in the **Deployments** panel of every issue referenced in the release, marked successful or failed, with the environment and a link back to codev. |
| A release is finalized                  | The deployment timeline is updated to reflect the finalized release.                                                                                                  |
| A build completes                       | A build entry in the **Builds** panel of the referenced issues, with a link to the run.                                                                               |

<figure><img src="/files/0WdaKqRsfXEYPZnW3nIc" alt="Jira project Development view listing successful deployments against the referenced issues"><figcaption><p>Deployments codev reports back, shown against the work items they reference (Jira project <strong>Development > Deployments</strong>).</p></figcaption></figure>

codev maps your environments to Jira's environment types — review and dev environments as *development*, test and snapshot as *testing*, and release as *staging*.

{% hint style="info" %}
**It can take a few minutes to appear.** Jira indexes deployment and build data asynchronously, so the **Deployments** and **Builds** entries may not show on an individual issue immediately — they usually appear within a few minutes, and can take longer the first time a new credential reports data. The project-level **Development > Deployments** view is the most reliable place to confirm the data has arrived.
{% endhint %}

{% hint style="info" %}
**Moving issues automatically.** codev writes deployment and build data but does not transition issues itself. Use a **Jira Automation** rule that reacts to the deployment data — for example, transition an issue to *Done* when it is deployed to your release environment.
{% endhint %}

## Self-hosting

The two methods work the same on a self-hosted instance, with the same Cloud-only restriction on OAuth write-back. Server-level configuration is covered in the [sfp server](https://docs.flxbl.io/sfp-server) documentation.

***

Once a read-capable integration is registered, see how detected issue keys appear across your pipeline.

{% content-ref url="/pages/EaEqKP4eZhO5DCoR1v9F" %}
[Work items](/flxbl/codev/ci-cd/work-items.md)
{% endcontent-ref %}


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/codev/integrations/issue-tracking/jira.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.