- What this recipe does
- Where to find it
- Who can use it
- Sync list
- Quick start - 10 steps
- Creating a sync
- Fields
- Issue types
- Status
- Comments
- Attachments
- Issue links
- Sub-tasks and Epics
- Triggers
- Deletion
- Jira Service Management
- Validation and pre-flight check
- Running a sync
- Sync conflicts
- Activity, failed items and recovery
- Notifications
- Export and import
- Limits
- Related
What this recipe does
Two-project sync keeps issues in two Jira projects paired: when an issue appears in one project, the app creates its counterpart in the other and then keeps the chosen fields, status, comments, attachments and links in step. Service projects (Jira Service Management) are supported on either side.
The sync is a standing recipe: you configure it once and it runs on a schedule, on Jira events, or when you click Sync now. It is not a script - no code is needed.
| Area | What syncs |
|---|---|
| Fields | Any field, per rule: a_to_b, b_to_a or both, with a conflict strategy |
| Issue types | Mapped per direction, auto-map by name; Epics optional |
| Status | Mapped per direction, with an optional resolution; moved by workflow transition |
| Comments | Off by default; posted as the original author, a bot account or the app |
| Attachments | Off by default; copied or linked to the original |
| Issue links | Off by default; recreated between counterparts |
| Sub-tasks | Created under the counterpart of the parent |
| JSM data | Request type, comment visibility, customer, organizations, participants, approvers (read-only), SLA snapshot, sanitization |
Where to find it
Admin Panel - Recipes tab. The tab has two sub-tabs:
- Two-project sync - the list of sync configurations and the New sync, Refresh, Export all and Import buttons
- Sync conflicts - values that need a decision (see Sync conflicts)
The one-shot bulk recipes (bulk update, bulk transition and so on) live on the Recipes tab of the Console instead - see Recipes.
Who can use it
- Only Jira administrators can open the Admin Panel and manage syncs.
- Each sync configuration belongs to the administrator who created it. Other administrators do not see it in their list and cannot edit, run, export or delete it. Plan ownership accordingly (for example, create shared syncs from a team admin account).
- Sync runs call Jira as the app, not as a user. Comments and attachments can be written under another identity - see Comments and Attachments, and Permissions setup.
- Every change to a configuration, every run start and every conflict decision is written to the settings audit log (see Audit logs).
Sync list
Each configuration is a row with these columns:
| Column | Meaning |
|---|---|
| Name | Configuration name |
| Projects | Project A and Project B keys |
| Status | Colour-coded state (see below); a Paused badge when the sync is paused, a Bot fallback badge when the last run had to write comments under the bot or the app instead of the original author |
| Last run | Time of the last run |
| Pending conflicts | Open items on the Sync conflicts tab |
| Failed items | Issues waiting for retry (dead-letter) |
| Actions | Sync now (or Resume sync when paused) and a menu |
Status colours:
| Colour | When |
|---|---|
| Grey | Disabled, or never run |
| Green | Last run succeeded with no errors |
| Yellow | Last run was partial, or there are failed items or pending conflicts |
| Red | Paused, or last run failed |
The row menu contains Edit, View activity, Backfill, Retry failed items (only when there are failed items and the sync is not paused), Export, Duplicate and Delete.
Duplicate asks for a new name (default <name> copy). Delete asks for confirmation; pending conflicts of the deleted sync are marked stale, and the option Also delete all conflict and run history removes the history too.
Quick start - 10 steps
These steps take a brand-new sync from zero to its first run. Each step links to the full reference below.
- Prepare. You need admin access to both projects. If comments or attachments should be written as a person rather than the app, invite a bot account first - see Permissions setup.
- Open the library. Admin Panel → Recipes → Two-project sync, click New sync.
- Basics. Enter a Name (for example
Support → Dev escalation) and a one-line Description. - Projects. Pick Project A and Project B. The editor shows the detected pair type: Jira ↔ Jira, JSM ↔ Jira or JSM ↔ JSM. With a service project in the pair, make it Project B.
- Narrow (optional). Add JQL filter A / JQL filter B, for example
labels = "sync-to-dev"orcreated >= -30d. - Fields. Click Add field for Summary, Description, Priority, Labels. Check the Field schema diff panel for incompatible types. For fields that should simply be copied, pick a strategy other than
manual_review(see the note in Fields). - Issue types and status. Click Auto-map by name and Suggest mapping, fix the rows that differ.
- Comments, attachments, links, triggers. Turn on what you need - all of them are off by default except manual runs.
- JSM (optional). Request type, comment visibility, customer policy, sanitization - see JSM specifics.
- Check and run. Click Run pre-flight check, fix every error under Issues with this configuration, Save, turn Enabled on, then Sync now. Watch the result in View activity.
Creating a sync
Click New sync. The editor is a single dialog with sections.
Basics
| Setting | Default | Notes |
|---|---|---|
| Name | - | Required, up to 255 characters |
| Description | empty | Up to 2,000 characters |
| Project A / Project B | - | Required and must be different |
| JQL filter A / JQL filter B | empty | Optional JQL that limits which issues of that project take part |
| Enabled | off | A new sync is saved disabled; turn it on when the configuration is ready |
After you pick both projects the editor detects the pair type and shows it: Jira ↔ Jira, JSM ↔ Jira or JSM ↔ JSM. The Jira Service Management section appears only for pairs that include a service project.
Which issues take part
A run looks at issues in both projects (narrowed by the JQL filters). An issue that has no counterpart yet gets one created in the other project, with the summary and description copied and the issue type taken from the issue type mapping. The pairing is stored on both issues as an issue property, so later runs update the same counterpart.
Fields
Each row of the Fields section is a field rule. Click Add field to add one.
| Column | Values | Default for a new rule |
|---|---|---|
| Field | A field of Project A | - |
| Direction | a_to_b, b_to_a, both |
a_to_b |
| Conflict strategy | source_of_truth, last_write_wins, manual_review |
manual_review |
| Source of truth | a, b |
- (used by source_of_truth) |
Up to 50 field rules per sync.
How a value is written. The app remembers what it last wrote into each field of the counterpart. If the target value is unchanged since that write, the new source value is written. If someone edited the target field in the meantime, or the pair has never been synced before, the rule’s conflict strategy decides. With manual_review the value is not written and an item is added to Sync conflicts.
Note: because
manual_reviewalso applies the first time a pair is compared, fields whose values differ on a freshly created counterpart go to Sync conflicts rather than being copied. Use a different strategy for fields that should simply be copied across.
Global settings below the rules:
| Setting | Values | Default |
|---|---|---|
| When value is unmapped | skip, fail, default |
skip |
| When target field is missing | skip, fail, default-value |
skip |
| Attempt type coercion (number↔text, single↔multi) | on / off | off |
Field schema diff
The Field schema diff panel compares the field schemas of both projects and marks each field as:
| Verdict | Meaning |
|---|---|
| Matched | Same type on both sides, safe to sync |
| Type coerce | Different types that can be converted (number↔text, single↔multi) - only with type coercion on |
| Type incompatible | Cannot be mapped without data loss |
| Missing in target / Missing in source | The field exists on one side only |
| JSM special (synced separately) | Organizations, participants, approvers - handled by the JSM section, not by field rules |
Auto-fill mapping by name fills missing value mappings where option names match.
Issue types
Issue type mapping has two tables, Project A → Project B and Project B → Project A. Auto-map by name fills missing rows where type names match.
| Setting | Values | Default |
|---|---|---|
| When source type is unmapped | Skip issue (warning), Fail and route to dead-letter, Use a default target type | Skip issue |
| Default type on project A / B | An issue type | - (needed for “Use a default target type”) |
| Sync Epics as the mapped target type (otherwise skipped) | on / off | off |
If no target type can be resolved, a counterpart is not created: the issue is skipped, or it fails and goes to the failed items list, depending on the policy.
Status
Status mapping is set per direction (Project A → Project B, Project B → Project A); each mapping can also set a resolution (optional). The Workflow diff panel compares both workflows, marks each source status as Matched, Suggested, No match or Unreachable, and Suggest mapping fills missing rows from suggestions.
| Setting | Values | Default |
|---|---|---|
| When status is unmapped | skip, fail, manual_review |
skip |
| Policy override (per source status) | Skip, Fail, Manual review, or the global policy | global |
The app moves the counterpart with a workflow transition. If the target status cannot be reached by a direct transition, or the transition needs a field that the sync does not write, the validation panel warns about it before saving. A transition rejected by Jira at run time is recorded under the Workflow transition error category.
Comments
| Setting | Values | Default |
|---|---|---|
| Direction | a_to_b, b_to_a, both, none |
none (comments are not synced) |
| Author | original, bot, app |
app |
| Bot accountId | A Jira account ID | empty |
| Prefix with ‘Original by @user’ | on / off | off |
| Copy mentions | on / off | off - mentions are replaced with plain @name text |
With original, the comment is posted as its original author when that user may add comments in the target project; otherwise the bot account is used, and then the app. A fallback shows the Bot fallback badge in the sync list. Comments already copied are marked, so they are never copied back or duplicated.
Attachments
Off by default.
| Setting | Values | Default |
|---|---|---|
| Transfer attachments | on / off | off |
| Mode | Copy the files, Link to the original | Copy the files |
| Direction | a_to_b, b_to_a, both, none |
both |
| Upload as | original, bot, app |
original (falls back to the bot, then the app, when the user may not attach files in the target project) |
| Max file size, bytes | number | 5 MB (cap 10 MB) |
| Max files per run | number | 20 (cap 50) |
| Max total size per run, bytes | number | 25 MB (cap 50 MB) |
- Copy the files uploads the file to the counterpart. A file is not copied again if the counterpart already has an attachment with the same name and size.
- Link to the original adds a remote link to the original file instead - nothing is downloaded and no extra storage is used. Repeated runs do not add duplicate links.
- A failure on one file is recorded for that issue and the remaining files are still processed.
Issue links
Off by default.
| Setting | Values | Default |
|---|---|---|
| Transfer issue links | on / off | off |
| When the linked issue is not synced | Skip the link, Link to the original issue, Report it in the run | Skip the link |
| Link type mapping | Source link type → target link type | empty - link types without a mapping are transferred unchanged |
- When both ends of a link are synced by the same configuration, the link is recreated between the two counterparts, keeping its direction.
- When the other end is not synced, the policy applies. Report it in the run creates nothing but reports the link on every run (so the issue stays in the failed items list) until the other end is synced or the policy changes.
- Existing links on the counterpart are checked first, so repeated runs do not create duplicates. The link between an issue and its own counterpart is never transferred.
Sub-tasks and Epics
- Sync sub-tasks - on by default. When off, sub-tasks are skipped entirely and no counterpart is created for them. When on, a sub-task’s counterpart is created under the counterpart of its parent if the parent is already synced; otherwise it is created without a parent link.
- Epics are skipped unless Sync Epics as the mapped target type is on (see Issue types).
Triggers
| Setting | Default | Notes |
|---|---|---|
| Run on schedule | off | Uses the app’s scheduled ticks |
| Schedule interval | hour |
fiveMinute, hour, day, week |
| Allow manual runs | on | |
| Trigger on Jira events | off | With Issue created, Issue updated, Comment added; Issue updated is pre-selected |
- A scheduled run processes issues updated since the previous run, oldest first, up to 50 issues per run. Failed items are retried first (up to 50 per run).
- Scheduled runs only happen while the Scheduled trigger type is enabled in Administration.
- Event runs sync the one issue the event is about. Comment added only copies the new comment and only when the issue already has a counterpart.
- Changes the app makes itself do not trigger new event runs, so a pair does not loop.
Deletion
| Option | Notes |
|---|---|
| Detach (default) | |
| Cascade (delete counterpart) | Asks for confirmation and is flagged as a warning by the pre-flight check |
| Leave alone |
The policy is saved with the configuration. Sync runs react only to issue created, issue updated and comment added; deleting an issue does not start a sync run.
Jira Service Management
Shown when at least one project is a service project. In a pair with a service project, make the service project Project B: for issues from Project A the app creates a customer request in Project B through the service desk (with a request type and a reporter); issues from Project B get a regular issue in Project A.
The section covers request type, comment visibility, customer / reporter, organizations, participants, approvers, SLA and sanitization - see JSM specifics.
Validation and pre-flight check
The editor validates the configuration as you type and lists problems under Issues with this configuration. A new sync shows them once both projects are chosen or after the first Save or Run pre-flight check, so an empty form opens without errors; an existing sync shows them right away. Save is blocked while any error remains (for example: missing name, the same project on both sides, a field not found in either project, a status not in the target workflow, a bot account that does not resolve to a Jira user).
Run pre-flight check re-runs the checks against the live site; the result and its time are shown as Last pre-flight and Pre-flight errors. The app also repeats the check automatically for configurations whose last check is older than 30 days.
Running a sync
| Action | What it does |
|---|---|
| Sync now | Starts a background job for issues updated since the last run |
| Backfill | Starts a background job over every issue in both projects (asks for confirmation; may run for a while) |
| Retry failed items | Starts a job that retries the issues in the failed items list |
A started job shows Job started (<id>). Runs execute in the background; check View activity for results.
Automatic pause
A sync is paused automatically:
- after 3 runs in a row in which more than half of the issues failed with the same error category, or
- when the type of one of the projects changes (for example, a software project becomes a service project).
A paused sync shows a red status and Resume sync instead of Sync now. Resume is refused while the pre-flight check reports errors (Cannot resume: N pre-flight errors must be fixed first.).
Sync conflicts
The Sync conflicts tab lists pending items: field conflicts, status changes with no available transition, and unmapped values. Each row shows the kind, the two issues, the field and the time it was detected.
| Action | Effect |
|---|---|
| Apply A / Apply B | Closes the conflict with the chosen side recorded |
| Ignore | Closes the conflict without a decision |
| Bulk apply A / Bulk apply B | Same for all selected rows |
Closing a conflict records the decision in the audit log; it does not itself write the value into the issue. Pending conflicts of a field are marked stale when you change that field’s direction or strategy, or delete the sync. Closed and stale items are removed after 90 days.
Activity, failed items and recovery
View activity opens the history of the sync:
- Recent runs - each run with its trigger and N ok / N failed / N skipped of N counts; filter by status and trigger; View sample shows the recorded errors
- Pending dead-letter items - issues that failed, with Source issue, Category, Error and Failed at; per item Retry this item or Mark ignored, and Mark all as ignored
Clicking an error opens Sync error with the category, HTTP status, endpoint, actor, correlation ID, a response body preview and a Suggested action. The error categories and what to do about each are listed in Troubleshooting.
Failed items that were ignored or later retried successfully are removed after 90 days; items still waiting for retry are kept.
Notifications
The Notifications bell in the Admin Panel header lists syncs that need attention: Paused, Recent run failed, Recent run partial, Items pending retry, Items stuck >30 days and Conflicts pending, each with Go to config.
Export and import
- Export (row menu) saves one configuration, Export all saves all of yours, as a JSON file. User references (bot, customer and similar account IDs) are left out of the file and the export reports how many were removed.
- Import reads such a file. Nothing is written until the whole file passes validation. When a name already exists: Skip (default), Overwrite or Rename.
- Imported configurations are disabled. Check the projects, issue-type and JSM mappings on this site, re-select the users, then enable each one.
Sync configurations can also be included in the full app export - see Import / Export.
Limits
| Limit | Value |
|---|---|
| Sync configurations (checked on import) | 50 per site |
| Configurations shown in the list | 200 per administrator |
| Field rules | 50 per sync |
| Name / description | 255 / 2,000 characters |
| Issues per scheduled run | 50 |
| Failed items retried per scheduled run | 50 |
| Automatic pause | after 3 consecutive failing runs with the same cause |
| Pre-flight re-check | when older than 30 days |
| Conflict and failed item retention | 90 days after closing |
| Attachments | see Attachments |
| Custom sanitization rules | 32 per sync |
Related
- Permissions setup - who the sync acts as, bot account, scopes
- Typical scenarios - three end-to-end configurations
- JSM specifics - request types, customer policy, sanitization
- Troubleshooting - failed items, Resume sync, error categories
- Recipes - one-shot bulk recipes
- Service projects - issue properties written by the app
- Import / Export - moving configurations between sites
- Audit logs - settings changes and run starts
- Administration - trigger type switches
