Frequently Asked Questions

Jira Sync (jira-push) — Frequently Asked Questions

General

What is jira-push?

jira-push is a Jira issue synchronization tool that syncs/migrates issues between Jira instances (Server/Data Center/Cloud). It supports bidirectional sync of issues, comments, attachments, workflow status, and more.

Which Jira deployment types are supported?

• Jira Server (legacy)

• Jira Data Center

• Jira Cloud

• Jira Service Management (JSM) / Jira Service Desk — both Data Center and Cloud

What sync directions are supported?

• Server/DC → Cloud

• Cloud → Server/DC

• Cloud → Cloud

• Server/DC → Server/DC

• Jira Core → Jira Service Desk (and vice versa)

Installation & Running

How do I install jira-push?

You can either:

1. Docker: docker pull xalt/jira-push then run with a mounted config file.

2. Binary: Download the Linux/macOS/Windows binary from the artifact repository and run directly.

3. From source: Clone the repo and run go run main.go pushIssues --config <configfile>.

How do I specify a config file?

Use the --config flag: ./jira-push pushIssues --config /path/to/.jira-push.yaml. If omitted, it looks for .jira-push.yaml in the home directory.

Can I run jira-push in Docker?

Yes. Mount your config file and run:

docker run -v $(pwd)/.jira-push.yaml:/.jira-push.yaml xalt/jira-push

Can I deploy jira-push on OpenShift / Kubernetes?

Yes, using Kubernetes Secrets for certificates and ConfigMaps for the config file. See docs/openshift-deployment-unverified.md — note this guide is currently unverified.

Authentication

What authentication methods are supported?

• Basic Auth (username + password) — Data Center

• Personal Access Token (PAT) — Data Center

• API Token (username/email + API token) — Cloud

How do I authenticate with Jira Cloud?

Set iscloud: true, use your email as the username, generate an API token from Atlassian API tokens, and set the token as your password. Also set your accountid.

Does jira-push support mTLS?

Yes, since v1.18.0. You can configure per-server mTLS with custom CA certificates, client certificates, and client keys under the tls: section. See docs/mtls-configuration.md for the full guide.

Can I use different auth methods for source and target servers?

Yes. Each server (serverfrom / serverto) has its own independent auth and tls configuration.

Configuration

What is the minimum configuration required?

You need serverfrom and serverto blocks with at least: host, auth (credentials), projectkey, issuetypes, and customfields (epiclink, epicname). Plus a pushJQL to select issues.

What does the pushJQL setting do?

It defines the JQL query used to select which issues to sync from the source server. Only one project is supported per JQL due to issue type and field constraints.

Can I sync multiple projects at once?

No. Currently only one project per configuration is supported because issue types and create/edit meta fields can differ per project. Run separate configs for each project.

How do I ignore specific issue types?

Set the issue type value to _ignore_ in the serverfrom.issuetypes mapping:

issuetypes:
  newfeature: _ignore_

What does Dummyusername do?

It sets a fallback username used when syncing user fields and the actual user cannot be found on the target system.

How do I use a proxy server?

Add proxyserver to the server config:

serverto:
  proxyserver: http://webproxy.example.com:8080/

What is isProbingEnabled?

When set to true, jira-push performs an HTTP probe to check server connectivity before syncing. Disabled by default; proxy is not yet supported with probing.

Comment Synchronization

How does comment sync work?

By default, comments sync one-way (source → target). To enable two-way sync, set syncComments: true or syncComments: "two-way" on the source server config.

Can I disable comment sync entirely?

Yes. Set syncComments: "disabled".

What about internal comments (JSM)?

Internal comments are not synced by default. Set syncInternalComments: true on the target server to enable this. Only works with isjiraservicedeskv2: true.

Attachment Synchronization

How does attachment sync work?

Similar to comments: one-way by default (source → target). Set syncAttachments: true for two-way, or syncAttachments: "disabled" to turn it off.

How do I handle large attachments?

Configure attachmentTimeoutMinutes (defaults to 30 minutes) on either server to adjust the upload timeout:

serverfrom:
  attachmentTimeoutMinutes: 15

Workflow Status Sync

How do I enable workflow status sync?

Add under syncSettings:

syncSettings:
  workflowStatus:
    enabled: true
    direction: one-way  # or two-way

What is the difference between one-way and two-way workflow sync?

• one-way: Source status changes are applied to the target.

• two-way: Status changes on either side are synced to the other. Requires a conflictResolution strategy.

What conflict resolution strategies are available for two-way workflow sync?

• serverPriority: One server always wins conflicts (source or target).

• latestStatusChangePriority: The most recent status change wins.

What happens if a workflow transition is not mapped?

By default, the sync process stops with an error. Set ignoreUnmappedTransitions: true to skip unmapped transitions instead.

Can I ignore a specific status in workflow mapping?

Yes, set the status transition to _ignore_:

6:  # closed
  default: _ignore_

What is identifierForPropertyKeys?

Used in multi-sync scenarios where the same issues are synced to multiple targets. It makes workflow property keys unique per sync configuration to prevent conflicts.

What does includeConfiguredUserChangesOn do?

By default, workflow sync ignores status changes made by the sync/technical user. This setting lets you include those changes for source, target, or both servers — useful in multi-sync setups or when the sync user also manually updates issues.

Is the old syncWorkflowStatus config still supported?

Yes, but it's deprecated. It only supports one-way sync. Migrate to the syncSettings.workflowStatus configuration.

Field Synchronization

Which people fields can be synced?

assignee and reporter, configured under syncPeopleFields. Users must exist on both systems with correct group/role permissions.

What system fields can be synced?

• Labels

• Fix Versions (one-way and two-way)

• Affects Versions

• Description (with default value support)

• Components (with default value support)

Can I override target labels on every sync?

Yes, set labelsOptions.overrideTargetLabels: true. Otherwise, labels added on the target are preserved.

How does version sync work?

Version sync creates missing versions on the target project. Options include:

• overrideTargetVersions: Keeps target versions identical to source.

• useMapping: Maps version names between source and target.

Which custom field types are supported for sync?

Source fields: select, multi-select, cascading select, textarea, float/number, text field, plus system fields (assignee, reporter, duedate, created). Target fields: textfield, textarea, float (float-to-float only).

Can I set default values for custom fields on issue creation?

Yes, via customFieldMapping.mappingWithDefaultValue. Supported types: radio button, text field, text area, date/time picker, date picker, single select.

User Mapping

How does user mapping work?

Enable userMappingEnabled: true on serverto and define mappings under userFieldMapping for reporter and/or assignee. Maps source usernames to target usernames (or Cloud account IDs).

Do users need to exist on both systems?

Yes, mapped users must have accounts and appropriate permissions on the target system.

Priority Sync

Can I sync priorities between systems?

Yes. Set syncPriorities: true on serverfrom and define a prioritiesFieldMapping with source-to-target priority ID mappings.

Jira Service Desk / JSM

How do I sync to a Jira Service Desk project?

Set isjiraservicedesk: true on the target server and configure servicedesk.id and servicedesk.requesttypes.

What is isjiraservicedeskv2?

A newer configuration that uses the Jira Core REST API instead of the Service Desk API for creating tickets. Required for Cloud JSM projects to avoid duplicate ticket creation.

How do I map issue types to request types?

Use servicedesk.issueTypeToRequestTypeMapping under serverto when using isjiraservicedeskv2: true.

Can I sync from Jira Software DC to Jira Service Desk Cloud?

Yes. Key differences: use username + API key auth, set isservicedesk: false, omit path and port, and use projectId for the service desk ID instead of request types.

Remote Links & Issue Identification

What does createTargetRemoteLink do?

When set to true on serverfrom, it creates a remote link on the source issue pointing to the created/synced target issue.

What is getIssueByIssuekeyCustomfield?

When set to true on serverto, jira-push looks up existing target issues by a custom field containing the source issue key (instead of searching by summary). This improves matching accuracy.

Can I remove the issue key from the summary?

Yes. Set removeIssueKeyFromSummary: true on serverto (only works when getIssueByIssuekeyCustomfield is enabled).

Syncing Issues Without Parent

Can I sync issues without their parent links?

Yes, since v1.17.0. Enable syncSettings.syncIssuesWithoutParent.enabled: true and configure conditions using either filterJql (JQL filter) or issueTypes (list of issue type IDs).

What fields are removed when syncing without parent?

• Cloud: The parent field.

• Data Center: Epic link, epic name custom field, and/or parent link custom field.

Troubleshooting

The sync created duplicate issues on the target. What happened?

Common causes:

• Target system indexing language prevents JQL from matching existing issues by summary.

• Service Desk Cloud API changes (use isjiraservicedeskv2 to fix).

• Consider enabling getIssueByIssuekeyCustomfield for more reliable matching.

Workflow sync stops with an unmapped transition error. How do I fix it?

Either add the missing status-to-transition mapping, or set ignoreUnmappedTransitions: true to skip unmapped transitions.

Attachments are timing out. What can I do?

Increase attachmentTimeoutMinutes (default is 30 minutes) on the relevant server configuration.

The sync user's status changes are not being synced. Why?

By default, status changes by the configured sync user are ignored to prevent loops. If you need to include them (e.g., in multi-sync scenarios), set includeConfiguredUserChangesOn to source, target, or both.

How do I enable debug logging?

Set the environment variable LOG_LEVEL=DEBUG before running jira-push.

mTLS connection fails. How do I troubleshoot?

See the detailed troubleshooting section in docs/mtls-configuration.md. Key steps:

1. Verify certificate files with openssl.

2. Test connectivity with curl --cert/--key/--cacert.

3. Enable debug logging.

4. Ensure certificates are PEM format and not expired.

config get Command

What does the config get command do?

It prints a human-friendly project configuration report for both servers based on your config file — including issue types, workflows, statuses, and optionally user data.

How do I save the report to a file?

Use --report to write a file, and optionally --report-path to specify the output location:

jira-push config get --report --report-path ./reports

Can I include user data in the report?

Yes, add --include-users to include display names and account IDs.

Versioning & Compatibility

Is the tool backward-compatible?

Yes. New configuration options like syncComments, syncAttachments, tls, and syncSettings are all optional and default to the previous behavior when not specified.