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

# Jira issue sync

> Connect Jira Cloud; your issues stay current in Orchestra, each person sees only what Jira shows them, and agents can file and update issues in Jira

Connect Jira Cloud and your Jira issues appear in Orchestra and stay current:
new issues, edits, status changes, assignees, labels, comments and links. A
synced issue keeps its Jira key as its ref (`LOOP-42`) and a link back to Jira,
and it lands already connected to the sessions, commits and pull requests that
name its key.

> [!NOTE]
>
> **Each person sees only what Jira shows them.** A Jira issue is never visible
> to your whole Orchestra workspace by default. Orchestra asks Jira which issues
> each person may browse, so an issue in a restricted project, or under an issue
> security level, stays hidden from anyone Jira hides it from, and from their
> agents too.

## Connect on Orchestra Local

On Orchestra Local each person connects with their own Atlassian account, in
one of two ways. Either way your laptop syncs with your own access, so you see
exactly what Jira shows you, and what Orchestra holds to reach Jira stays in
your keychain.

**Sign in with Atlassian (recommended).** In the desktop app, open **Settings,
Integrations** and choose **Sign in with Atlassian** on the Jira card, or run:

```bash theme={null}
orchestra connect jira
```

Your browser opens Atlassian's consent screen. Approve it and pick your site;
the browser then hands the sign-in back to your laptop. Atlassian requires the
app's secret for this step and for each renewal, so Orchestra's API completes
them on your laptop's behalf: the sign-in is sealed so only your laptop can open
it, and Orchestra keeps none of it. Your issues still come straight from Jira
to your laptop.

**Or use an API token.** Create one at
[id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens),
then fill in the token form on the Jira card (your site, your Atlassian email,
the token, and optionally project keys such as `LOOP, OPS`), or run:

```bash theme={null}
orchestra connect jira --site acme.atlassian.net --email you@acme.com --projects LOOP,OPS
```

The token is asked for without echoing it, and nothing about it goes through
Orchestra's servers.

`orchestra integrations status jira` shows the site, the projects and the last
sync, and `orchestra disconnect jira` removes the sign-in or token from your
keychain.

Your laptop syncs with your own login, so you see exactly what Jira shows you.
Issues from Jira are never shared with teammates through git: each teammate's
laptop syncs what their own Jira login can see.

## Connect a hosted workspace

A workspace admin chooses **Connect** on the Jira card in **Settings,
Integrations** and approves Atlassian's consent screen. Orchestra asks to read
your Jira projects, issues and people, and to manage the webhooks that send
changes within seconds. If your login reaches several Jira sites, Orchestra
connects the first one and names the others.

To check who may see each issue, Orchestra asks Jira on behalf of every person
in the workspace. Jira only answers that for a Jira administrator, so **connect
with a Jira administrator account**. If the account that connects is not one,
synced issues are visible only to that person until an administrator connects.

People are matched to their Jira accounts by email. Someone whose Jira email
differs from their Orchestra email can choose **Link my Jira account** on the
Jira card; Orchestra only learns who they are in Jira and keeps nothing else.

## Writing issues to Jira

The connection starts read-only. A workspace admin can choose **Allow Orchestra
to write issues** on the Jira card; Atlassian's consent screen asks again, this
time to create and update issues, and to rename a project or change its
description (Jira lets that only for people who administer the project). A
workspace that allowed writes before can choose it again to add project
changes; its issue writes keep working either way. On Orchestra Local your own login decides:
whatever Jira lets you do, Orchestra can do for you. Writes also need write-back
turned on, for the workspace or for the issue's team: see
[Writing back to trackers](https://docs.orchestrahq.ai/integrations-write-back.md).

From then on, for issues in Jira:

* **New issues are created in Jira.** New issue in the app, and `save_issue`
  from an agent, create the issue in the project you name (`team: "LOOP"`) and
  answer with Jira's key, link and status.
* **Edits go to Jira.** Title, description, priority, assignee, labels, parent,
  blocking links and web links.
* **Statuses follow your workflow.** Status is set by name, and Orchestra moves
  the issue through your project's own workflow. When the workflow has no move
  from where the issue is to the status you asked for, nothing changes and the
  answer names the statuses it can move to from here. Agents can list a
  project's statuses with `get_me` and `get_issue_template`.
* **Comments are posted in Jira.** `add_issue_comment` on a Jira issue posts the
  comment there.
* **Refusals are Jira's words.** When Jira says no (a missing permission, a
  required field, a workflow condition), the error is Jira's own sentence and
  nothing is written anywhere.
* **People, not agents, are Jira assignees.** To put an agent on an issue, leave
  the assignee empty and dispatch the agent to it.

Orchestra never deletes anything in Jira.

Each change Orchestra would write to Jira waits for the approval of the person
who made it, on the issue's page. Nothing is written to Jira without it. See
[Writing back to trackers](https://docs.orchestrahq.ai/integrations-write-back.md).

## Agents recall issues

Agents and Ask AI can find a Jira issue or comment by what it says, with
`recall`, and cite it by key (`jira: LOOP-42`). Each person's agents find only
the issues that person can see in Jira, and only an issue's current text.

## Sessions and pull requests

Any session, commit or pull request that names a Jira key (`LOOP-42`) links to
that issue, and the issue shows the sessions behind it. A pull request links
when its title or description names the key, even if no commit message does.

## What stays current, and how fast

| Where | How changes arrive |
| - | - |
| Orchestra Local | Your laptop asks Jira for changes every few minutes while the app is open, and right after you write. |
| Hosted | Jira sends each change within seconds; a sync every few minutes catches anything missed. Who may see each issue is checked again every few hours. |

## When an Atlassian account is closed

Orchestra keeps the name and email Jira shows for an assignee or a comment's
author. It reports those Atlassian accounts to Atlassian every week, as
Atlassian requires. When Atlassian says an account was closed, Orchestra removes
that person's name and email within a day and keeps the issues and comments
themselves.


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