Jira sync
Route: /org/tasks → the Jira button · Permission: Configure Jira sync, mappings and run syncs
1. What Jira sync is
A per-project link between an Orbit project and a Jira project. Jira issues are imported as Orbit tasks, and their fields are translated through mappings you define once.
Sync is one-way by default — Jira to Orbit. Pushing changes back is an opt-in setting.
| Orbit | Jira | |
|---|---|---|
| Owns the issue | No, by default | Yes |
| Statuses | Project statuses | Jira workflow statuses |
| Grouping | Categories | Epics or components |
| Custom fields | Not supported natively | Imported read-only |
2. How sync spreads across the application
Imported tasks are ordinary tasks. They appear on the board, in analytics and in billing like any other — with a Jira badge linking back to the issue.
3. Setting it up — the six-step wizard
First-time setup is a wizard; afterwards the drawer opens on a summary.
On a project that has never been configured this opens as a six-step wizard. On a configured one it opens straight onto the summary shown below.
| Step | Title | You choose |
|---|---|---|
| 1 | Connection | Which Jira connection to use |
| 2 | Jira Project | The Jira project, searchable |
| 3 | Field Mapping | Status, priority and issue-type mappings |
| 4 | Custom Fields | Which Jira custom fields to import |
| 5 | People & Categories | Assignee mapping, and where categories come from |
| 6 | Review | Confirm and save |
Step 3 · Field mapping
Three independent maps: Status Mapping, Priority Mapping and Issue Type Mapping, each pairing a Jira value with an Orbit one. A default task type covers unmapped issue types.
Step 5 · Where categories come from
| Source | Behaviour |
|---|---|
| Epics (recommended) | "Story/Task/Bug grouped under an Epic — matches work items under a Category." Selected epics become Orbit categories |
| Components | "Issues carry components; the first mapped component becomes the category." |
| None | "Do not assign categories from Jira." |
Choosing epics and confirming them creates Orbit categories and records the pairing.
4. Running a sync — and the trap in it
The summary carries the whole configuration — connection, Jira project, every mapping — and the two sync buttons. Which of those two you press is the single most consequential choice on this screen.
Two buttons, and the difference between them matters more than anything else on this page.
| Button | Reads | Speed |
|---|---|---|
| Sync | Only issues Jira marked as updated since the last run | Fast |
| Resync All | Every issue in the Jira project | Slow |
The incremental sync asks Jira for issues updated since the last run. Changing an epic, assignee or type mapping in Orbit does not touch anything in Jira, so those issues are not returned and the new mapping never reaches them.
The confirmation says so outright:
Re-reads every issue in the Jira project and re-applies the current mapping — use this after changing the epic, assignee or type mapping, since those changes do not mark issues as updated in Jira. Slower than a normal sync; imported tasks are updated in place, not duplicated.
Change a mapping → run Resync All. Otherwise the change silently applies only to issues someone happens to edit in Jira afterwards.
Resync All updates tasks in place. It does not duplicate them.
The category-only shortcut
Because remapping epics is the most common mapping change, the category rail on /org/tasks offers a
category-only resync that rewrites just category_id. It reports three numbers:
| Number | Meaning |
|---|---|
n task(s) re-categorised | Updated |
n not imported yet — run a full Jira sync | The issue has never been imported |
n with no mapped epic | The issue's epic is not in the mapping |
5. Field reference — the settings
| Setting | Holds |
|---|---|
| Connection | Which Jira site |
| Jira project | Key, id and name |
| JQL filter | Narrows what is imported |
| Status / Priority / Type map | Jira value → Orbit value |
| Default task type | For unmapped issue types |
| Assignee map | Jira account → Orbit user |
| Epic map | Jira epic → Orbit category |
| Category source | epic · component · none |
| Field map | Which custom fields to import |
| Sync comments | Default on |
| Sync activity | Default on |
| Sync subtasks | Default on |
| Two-way sync | Default off |
| Last sync | Timestamp, status, error and count |
What imported custom fields look like
They appear on the task in a Jira Fields (n) tab, headed:
Custom fields from
<issue key>— read-only, refreshed on every sync.
Short values sit in that tab as a key/value grid; long text values become tabs beside the description. All of it is read-only and replaced on each sync.
Two-way sync
Off by default. Enabled, Orbit changes are pushed back to Jira. It is loop-safe — a change arriving from Jira is not pushed back out again.
With it off, Jira is the source of truth and an Orbit edit is overwritten on the next sync. With it on, both sides can write. Half-answering that question is how fields end up flapping.
6. The admin contract
| Prerequisite | Without it |
|---|---|
| Configure Jira sync, mappings and run syncs | No Jira button at all |
| A configured Jira connection | Nothing to pick at step 1 |
| Orbit statuses, priorities and types | Nothing to map to |
| A default task type | Unmapped issue types cannot be imported |
| Project members | The assignee map has no Orbit side |
7. Downstream
| Effect | Detail |
|---|---|
| Tasks created and updated | In place, never duplicated |
| Categories created | When epics are confirmed |
| Activity entries | Sync-written changes appear in the activity log |
| No notifications | See below |
The sync worker runs without the notification services attached, so an assignment made by Jira notifies nobody. Someone can be given fifty tasks and never be told.
Assignments made in Orbit notify normally. Only sync-driven changes are silent.
8. Don't confuse this with…
| Thing | Where | Why it is different |
|---|---|---|
| Sync | The drawer | Incremental — misses mapping changes |
| Resync All | The drawer | Every issue — the only way to apply a mapping change |
| Category resync | The category rail | Category only, fast |
| Two-way sync | A setting | Pushes Orbit changes back |
| Jira Fields tab | The task | Read-only imported custom fields |
9. Troubleshooting
| Symptom | Cause |
|---|---|
| A mapping change had no effect | Run Resync All — a normal sync will not reach those issues |
| Tasks have no category | Category source is none, or the epic is unmapped |
not imported yet — run a full Jira sync | The issue has never been imported |
| Tasks arrive with the wrong type | The issue type is unmapped and fell back to the default |
| Assignees are blank | The Jira account is not in the assignee map |
| Nobody was notified about an assignment | Sync-driven changes send no notifications |
| Custom fields are not editable | They are read-only and refreshed every sync |
| An Orbit edit was overwritten | Two-way sync is off; Jira wins |
| No Jira button | Missing Configure Jira sync, mappings and run syncs |
Related
- Task detail — the Jira Fields tab
- Categories — what epics become
- Activity history — where sync changes show up