> ## 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.

# Writing back to trackers

> Choose whether Orchestra creates and changes issues in Linear, Jira or GitHub, for the whole workspace and for each team

Orchestra reads your Linear, Jira or GitHub issues from the moment you connect. Whether
it also **writes** to them (creating issues there and saving edits there) is a
separate choice, and it is off until someone turns it on.

Three things decide whether a change is written to your tracker:

1. **Write access.** The connection has to be allowed to write: the second
   consent on the Linear or Jira card ("Allow Orchestra to write issues"), or,
   on Orchestra Local, your own login.
2. **Write-back is on** for the workspace, or for the issue's team.
3. **The person who made the change approves it.** Orchestra never writes to
   your tracker without that approval, every time.

When write access or the setting is missing, Orchestra keeps the work here: a
new issue is an Orchestra issue (`W-12`), an edit to a synced issue changes
Orchestra's copy, and your tracker is not called. Nothing is ever deleted in
your tracker.

## Every write waits for approval

One exception: when a team's **Status from agents' work** is Automatic, the status
changes agents' work makes to an issue already in Jira or Linear are approved by
that setting (see [Issues from agents' work](https://docs.orchestrahq.ai/issues-from-agent-work.md)).

With write-back on, a change bound for your tracker (a new issue, a title,
status, description, priority, assignee or labels, or a comment) is saved in
Orchestra at once and waits there. The issue's page shows what waits:

* **Write to Jira** (or Linear) writes exactly those changes, and the issue
  follows your tracker from then on.
* **Keep in Orchestra** writes nothing. The change stays here.

Only the person who made the change can approve it. Everyone else sees who it
is waiting for. That person also gets an Inbox item for each issue with
changes waiting. If your tracker refuses a change when it is approved (a plan
limit, a workflow that does not allow the move), its words are shown and the
change keeps waiting, so you can fix it or keep it in Orchestra.

## Projects

A project synced from Linear or Jira asks the same way. A new name or
description given to it in Orchestra waits for the approval of the person who
made the change; approve it on the project's page (**Write to Linear** or
**Write to Jira**) and Orchestra writes it there, or keep it in Orchestra. A
project's colour and leads are Orchestra's own and never wait. For Jira, the
connection must have been allowed to change projects (choose **Allow Orchestra
to write issues** again if it was allowed before 2026-11-19), and Jira writes a
project change only for a login that administers that project.

## GitHub issues

GitHub issues follow the same setting and the same approval. A change made in
Orchestra to an issue that lives on GitHub (its title, description, status,
labels or a comment) waits for the approval of the person who made it, and
**Write to GitHub** writes it with that person's own GitHub login. A new issue
an agent opens for a repository waits the same way, as an Orchestra issue,
until it is approved.

Your GitHub login stays on your laptop, so GitHub changes are written from
Orchestra Local there. Approve them in Orchestra on that laptop. On the hosted
app, a change to a GitHub issue stays in Orchestra.

## The workspace's setting

In **Settings, Integrations**, the **Write issues back to trackers** card turns
write-back on or off for the whole workspace. Only a workspace admin can change
it; everyone can see it.

* Write-back is **off** by default, for every workspace and every team, until
  an admin turns it on.

## When write-back is off

Changes you make in Orchestra to a synced issue are kept in Orchestra, and
your tracker keeps its own version. Orchestra tells you when that happens:

* On the issue's page, a note lists what was kept here (fields changed and
  comments written) and who can turn write-back on. A workspace admin gets a
  link to Settings; when it is off for the issue's team, the link opens the
  team's page. Choose **Got it** to stop seeing the note.
* An agent that edits or comments on a synced issue is told the change was
  kept in Orchestra, and who can turn write-back on, so it can tell you.

## A team's setting

A team can choose for its own issues, on the team's page:

| Setting | What it means |
| - | - |
| As the workspace | The team follows the workspace's setting. This is where every team starts. |
| On | The team's issues are written to your tracker, even when the workspace is off. |
| Off | The team's issues stay in Orchestra, even when the workspace is on. |

An issue's team is the Orchestra team it is on. An issue on no team follows
the workspace.

## Who can change what

| | Workspace setting | A team's setting | A team's roles |
| - | - | - | - |
| Workspace admin | Yes | Yes | Yes |
| The team's admin | No | Yes | Yes |
| The team's lead | No | No | No |
| Everyone else | No | No | No |

Roles are set on the team's page, next to each member: **Member**, **Lead** or
**Admin**. A role counts only while that person is on the team.

## Agents follow the same rule

An agent saving an issue with `save_issue`, or commenting with
`add_issue_comment`, is held to the same settings as a person on the page.
When write-back is off, the agent's issue is an Orchestra issue and its answer
says so. When it is on, the change is saved in Orchestra and waits for the
approval of the person the agent works for. Its answer says who will approve
it and that nothing was written to your tracker yet. Moving native issues to
your tracker from **Settings, Integrations** is your own action, so it writes
when you confirm it.

Every change to these settings, every write request and every approval or
decline is recorded with who made it and when.


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