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

# Jira Integration

> Hand PB jobs to Jira, get completion signals back, two Make scenarios, no code.

A new ProductBrain **Job** creates a Jira issue (Story by default. Change the issuetype in the blueprint). That container reaching **a done status category** marks the job **`done`**. Nothing else crosses the seam.

## Setup

<Steps>
  <Step title="Import the blueprints">
    From the repo: [`pb-to-jira`](https://github.com/moxzas/productbrain/blob/main/integrations/make/pb-to-jira.blueprint.json) and [`jira-to-pb`](https://github.com/moxzas/productbrain/blob/main/integrations/make/jira-to-pb.blueprint.json). In Make: *Create a new scenario → ⋯ → Import Blueprint*.
  </Step>

  <Step title="Create the webhooks">
    In each scenario, open the first module and create a new custom webhook. Copy both URLs.
  </Step>

  <Step title="Fill the placeholders">
    Scenario A (PB → Jira): your site URL (`YOUR_SITE.atlassian.net`), project key, and a Basic auth value. `base64(your-email:api-token)` (create the token at id.atlassian.com → Security). Scenario B: your ProductBrain API key (Settings → API Keys).
  </Step>

  <Step title="Point ProductBrain at Make">
    ```bash theme={null}
       curl -X POST "https://productbrain.com/api/v1/webhooks" \
         -H "Authorization: Bearer $PB_API_KEY" \
         -H "Content-Type: application/json" \
         -d '{"projectId": "YOUR_PROJECT", "url": "<scenario A hook URL>", "events": ["node.added"]}'
    ```
  </Step>

  <Step title="Point Jira at Make">
    Jira → Settings → System → Webhooks → new webhook with Scenario B's URL, event *Issue: updated*. Optionally scope it with JQL on your project label, which Scenario A adds to every issue it creates: `labels = "pbp-my-project"`.
  </Step>

  <Step title="Turn both scenarios on">
    Create a job in ProductBrain, Jira issue appears. Complete it, the job shows `done`.
  </Step>
</Steps>

## How the linkage works

The issue carries two labels: `pb-job-12` and `pbp-my-project`. Scenario B parses them, Jira Cloud webhooks deliver descriptions in ADF format, so labels are the reliable carrier. Don't remove the `pb-` labels.

## Claim an existing issue

Already have a Jira issue for the work? Link it to a job by hand. Add the same two labels Scenario A would have written:

* `pb-job-12`, where `job-12` is the job's ID in ProductBrain
* `pbp-my-project`, where `my-project` is your ProductBrain project ID

Type them exactly as shown, lowercase. When the issue reaches a done status category, Scenario B marks the job `done`.

This works because Scenario B never checks who created the issue. Its filter has two conditions: the status category key equals `done`, and the joined labels contain `pb-job-`. The job ID and project ID then come from the labels alone. Things to know:

* **Both labels are required.** The filter only looks for `pb-job-`. Without `pbp-`, Scenario B reads the wrong project ID and the update fails.
* **One job per issue.** With two `pb-job-` labels, Scenario B uses the last one.
* **Labelling a finished issue.** If the issue is already in a done status, adding the labels is itself an update, so expect the job to be marked `done` straight away.
* **Check for a twin.** If Scenario A was on when the job was created, Jira already has a Story with these labels. Remove the `pb-` labels from the one you don't want, or the first of the two to finish marks the job `done`.
* **JQL scope.** If you scoped the Jira webhook on your `pbp-` project label, as the setup suggests, the two labels above already match it. A scope on any other label needs that label on the issue too, or Jira never sends the update.

<Note>This section is read from the two blueprints, not tested against a live Jira site.</Note>

## When does a job become `done`?

In ProductBrain, `done` means the work is live in production. The integration marks the job `done` when its Jira issue reaches a done status category, so point the trigger at the state your team uses for shipped work. If your team closes tickets before a release goes out, move the trigger to the status that means released, or jobs will read `done` early.

<Note>Verified with live Make scenarios against payloads in Jira's documented webhook shape. The first run on your Jira site is the final validation.</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.