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

# JIRA

> Dispatch Cliq teams from any JIRA issue and post run status back as comments.

<div className="cliq-kicker">Integrations</div>

The **Cliq for JIRA** app connects a JIRA workspace to a Cliq
realm so ticket owners can dispatch team runs straight from an
issue and watch progress land back as comments.

* **Who it's for**: engineering / support teams that already
  triage in JIRA and want to hand tickets off to Cliq teams
  (PR drafters, incident responders, cleanup crews) without
  copy-pasting.
* **What it costs**: free — an Atlassian Forge app you install
  from the marketplace; runs entirely inside your Atlassian
  tenant. Uses your existing Cliq subscription.

## What you get

| Surface | What it does |
| - | - |
| **Issue panel** | Pick a team, review auto-filled inputs (summary, priority, labels come from the ticket), click Dispatch. |
| **Live status** | The panel polls every 5 seconds. Watch runs go from ● Running → ⏸ Awaiting input → ✓ Completed without leaving the ticket. |
| **Comment writeback** | Cliq posts one comment per lifecycle event: started, awaiting input, PR opened / merged, completed / failed. |
| **Realm bindings** | Bind each JIRA project to a different Cliq realm — support tickets go to the support realm, engineering tickets to the eng realm. |

## Prerequisites

1. **Atlassian site admin** on the JIRA workspace you want to
   connect.
2. **Cliq realm admin** on the realm you want to bind — the
   [least-privilege PAT](/auth) needs the `dispatch` and
   `read:realms` scopes only. No `admin` needed.
3. At least one team [published](/running-teams) to that realm.

## Install

Install from the [Atlassian Marketplace](https://marketplace.atlassian.com/apps/cliq-jira)
or, for a scratch tenant, via the Forge CLI:

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
forge install --site <your-site>.atlassian.net --product jira
```

Then in JIRA:

1. Go to **Apps → Manage your apps → cliq**.
2. Paste a Cliq PAT (create one with `cliq auth token jira` or
   from the [tokens page](https://cliqhub.io/settings/tokens)).
   Its grant needs `realms` read and `dispatch` write access.
3. Click **Load realms**, pick the realm to bind, click
   **Connect**.

That's it — you can start dispatching from any issue.

<Note>
  Behind the scenes, connect calls `POST /v1/integrations/jira/register`
  on cliqhub, which provisions a notification channel with an
  HMAC secret. Every subsequent event fires through that channel;
  rotating the secret from the settings page invalidates the old
  one immediately.
</Note>

## Bind projects to realms

By default, every JIRA project falls back to the account
default realm you picked on Connect. Override per-project on the
settings page:

| Column | What it means |
| - | - |
| **Project** | Every project on the site. |
| **Realm** | Cliq realm the panel targets for issues in that project. Empty → use the default. |
| **Default** | Radio button — the realm used when a project has no explicit binding. |

Bindings persist across app updates. Renaming a JIRA project
doesn't break the binding (Atlassian project IDs are stable).

## Dispatch from an issue

Open any issue → the cliq panel appears in the sidebar.

1. **Team picker** — shows every team published to the bound
   realm.

2. **Input form** — auto-populates from the issue:

   | Team input | JIRA source |
   | - | - |
   | `jira_key`, `key`, `issue_key` | Issue key (e.g. `MEAS-42`) |
   | `summary`, `title`, `jira_title` | Issue summary |
   | `description`, `body`, `jira_body` | Issue description (converted to plain text) |
   | `assignee`, `assigned_to` | Assignee display name |
   | `reporter` | Reporter display name |
   | `labels`, `tags` | Comma-joined issue labels |
   | `priority` | Issue priority name |
   | `epic`, `epic_key` | Parent epic key (if set) |
   | `project`, `project_key` | Project key |
   | `status` | Current issue status |
   | `issue_url`, `jira_url` | Deep link to the issue |
   | `issue_type` | Story / Bug / Task / etc. |

3. **Dispatch** — the run enqueues on cliqhub. A 🤖 comment
   appears on the issue within a couple of seconds.

## What lands on the issue

Every lifecycle event posts a comment:

| Event | Comment |
| - | - |
| Run started | 🤖 Cliq run started — `<team>` · \[watch] |
| Awaiting input | ✋ Waiting on input · \[answer in cliq] |
| PR opened | 🔀 PR opened: `<title>` · \[run] |
| PR merged | 🔀 PR merged in `<sha>`: `<title>` · \[run] |
| Completed | ✓ Cliq run completed |
| Failed / crashed | ✗ Cliq run failed — `<error>` |

Each comment links back to the run in cliqhub for the full
timeline.

<Note>
  Automatic **issue transitions** on PR merge or run completion
  are opt-in and configured per-project — coming in a future
  release. Today, the app writes comments and remote links only;
  transitions stay in your hands (or your GitHub-JIRA connector's,
  if that's already wired up).
</Note>

## The PR loop

Teams that ship a `pull_request` artifact (via an `open_pr`
phase) get extra treatment:

* The panel shows a **PR** chip next to the run row that opens
  the PR in a new tab.
* The issue's **Development** section (or "Web links") gets a
  remote link to the PR, tagged with the originating run id.
* On merge, both cliq (via an `after_pr_merge` phase) and your
  native GitHub-JIRA connector may fire. The app dedupes
  first-write-wins per (issue, PR) so you never get a double
  comment or a double transition.

## Rotate the webhook secret

The **Webhook** card on the settings page shows:

* Recent delivery count (24h) and success ratio.
* Last delivery id and timestamp.
* **Rotate secret** — mints a new HMAC key on cliqhub; from
  then on the Forge app rejects any delivery signed with the old
  key. The new key is shown once — copy it into your ops vault
  if you want an out-of-band backup.

## Uninstall

Uninstall from **Apps → Manage your apps → cliq → Uninstall**.
On uninstall the Forge Storage is purged (credentials, run
cache, delivery idempotency keys, PR-merged markers). Reinstall
starts you back at "not connected"; you'll need to reconnect a
PAT to resume.

The cliq-side `notification_channels` row **isn't** deleted on
uninstall — cliq keeps it around so you can rebind the same
JIRA workspace to a different Cliq realm later without re-
provisioning. Delete it manually with
`POST /v1/notification_channels/remove` (Hub API) if you want a
completely clean slate.

## Troubleshooting

| Symptom | What's usually wrong |
| - | - |
| **Panel says "not connected"** on every issue after Connect succeeded | Feature flag `VITE_ENABLE_JIRA_INTEGRATION` off on the cliqhub SPA (temporary, dev-only). Ping support. |
| **"Load realms" returns empty** | The PAT's grant lacks `realms` read access, or its user is in no realm. Mint a token with the right grant. |
| **Dispatch button disabled** | Selected team has required inputs with no auto-fill source and no manual entry. Fill them and it enables. |
| **No comments landing on the issue** | Check the **Recent deliveries** card on the settings page. 401 → secret drift, rotate. 5xx → cliqhub degraded, check status page. 404 → app uninstalled from JIRA. |
| **Duplicate comments on PR merge** | Should not happen after slice 5.3. If it does, file a bug with the two `X-Cliq-Delivery` ids. |

## Support

* **Docs** — this page.
* **Bugs / feature requests** — [support@getcliq.io](mailto:support@getcliq.io) or file an
  issue on [cliq-jira](https://github.com/getcliqio/cliq-jira).
* **Marketplace listing** —
  [https://marketplace.atlassian.com/apps/cliq-jira](https://marketplace.atlassian.com/apps/cliq-jira).


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