Jira Software AirSync

Connect Jira Cloud or Jira Data Center to DevRev using AirSync, and use DevRev for both support and build or just for support.

🔗 For more information, refer to the Jira AirSync snap-in on the DevRev marketplace.

You can also install the DevRev for Jira app in your Atlassian organization for additional features and a better experience. For deployments behind a firewall or using legacy Jira Server, see Jira Server AirSync.

Supported objects

The following tables list Jira Software objects and their corresponding DevRev equivalents. ✅ indicates the object is supported for that sync direction; ❌ indicates it is not supported.

Jira Cloud

Jira Data Center

Jira Data Center AirSync has been tested with and supports Jira Data Center 10.3 and later.

Use cases

Migrate from Jira to DevRev

In this scenario, the goal is to replace Jira with DevRev. Once the migration is complete, work that was previously done in Jira continues in DevRev. This approach can also be used to evaluate DevRev with real data.

To migrate from Jira to DevRev:

1. Perform a project import to migrate an entire Jira project into DevRev.

2. (Optional) Perform a sync from Jira to DevRev to bring over changes made after the initial import. Repeat this step as needed until the cutover is complete.

Build with Jira

In this scenario, Jira remains the system of record for development work while DevRev handles support (tickets, customer conversations, issues) and product planning. Development work continues in Jira and syncs to DevRev issues, allowing you to search Jira issues and link them to customer tickets without leaving DevRev. You can also use DevRev's Convergence snap-in to automatically update tickets and conversations based on issue updates in Jira.

⚠️ Warning: Setting up bidirectional sync incorrectly can result in duplicate or conflicting records. DevRev strongly recommends using a dedicated Jira administrator account, not a personal user account, to create the Jira connection and configure the import. This prevents individual Jira users from receiving excessive notifications and ensures sync operations are not disrupted if a user account changes.

To set up Jira for ongoing development sync:

1. Perform a project import to migrate the entire Jira project into DevRev.

2. Configure the sync-to-Jira recipe by running a sync from DevRev to Jira, which sets up the mapping for the outbound direction.

3. Enable periodic sync so that changes are automatically synced to and from the Jira project on an ongoing basis.

4. (Optional) Mark individual DevRev work items for syncing if you want issues created in DevRev to appear in Jira. Without this step, only changes to previously imported issues are synced to and from Jira.

Jira permissions

The permissions available to DevRev's Jira AirSync are based on the user who authorizes the connection. While DevRev requests comprehensive OAuth (Jira Cloud only) scopes for seamless integration, your actual access is limited by what the authorizing user can do in Jira for the specific project(s) being imported.

Required Jira permissions for a successful import

These permissions are required for a successful import:

• Browse projects: The user making the connection needs this permission for the projects they want to sync. Verify beforehand that the user can browse issues in the project they wish to bring into DevRev.

• Create issues: Jira requires this project-scoped permission not only to create issues but also to extract issue types. It is required for successfully mapping issues to their respective subtypes in DevRev. Verify beforehand that the user can create issues in the project they wish to import.

• (Jira Cloud only) read:jira-work OAuth scope: This scope is required for issue type and issue link type extraction.

For best results, perform imports using an administrator account on the external source. This ensures all necessary permissions are available to complete the import successfully.

If the Jira project is set to Private, the global Jira administrator can access its settings but cannot see the issues or most of the project data. To access the issues, set the global Jira administrator as a project administrator for that particular project.

Recommended permissions and scopes for a full import

The following permissions and scopes are recommended as they allow for a full import, making the most of the AirSync functionality.

The Administer Jira global permission is required for:

• Custom field extraction: Without extracting custom fields, AirSync cannot load them into DevRev. This can cause problems on reverse syncs if any of these fields are marked as required by Jira on issue creation.

• User extraction (Jira Data Center only): Admin permissions are required to access application roles, which contain the users that have access to the Jira application. Without this permission, no users are extracted.

• Permissions AirSync (Jira Cloud only): Without admin permissions, extraction of all relevant Jira objects referenced by the project permission scheme is not possible.

The Administer Jira global permission (Jira Cloud and Data Center) and the manage:jira-project OAuth scope (Jira Cloud only) are required for:

• Workflow and workflow scheme extraction: Without extracted workflows, AirSync cannot create custom stages in DevRev, and stages do not map one-to-one. Stages can still be mapped manually; for example, Done in Jira to Completed in DevRev.

📝 Note: For Jira Data Center, workflow extraction captures statuses but not transitions. In DevRev, all transitions are therefore permitted. This can be edited manually in DevRev.

Recommended permissions for syncing to Jira

The following permissions are usually enabled by default: assign issues, edit issues, transition issues, close issues, link issues, resolve issues, add comments, edit own comments, create attachments. Without the respective permission, certain actions fail. For example, without the add comments permission, AirSync cannot create comments.

⚠️ Warning: AirSync does not handle all custom field validations. While some common scenarios are covered (for example, an empty issue description that Jira rejects), Jira supports many validator options and configurations. Remove validators in Jira wherever possible. Where removal is not possible, recreate the validations in DevRev.

Permissions AirSync

By default, Jira Cloud AirSync includes permissions AirSync alongside other items. Permissions brought in are scoped to CRUD operations on issues for the synced project and appear in the mapping screen as Authorization policies. All groups, project roles, or users that hold one of the following Jira permissions have a counterpart created in DevRev: Create Issues, Browse Projects, Edit Issues, Delete Issues. These permissions apply only to synced issue subtypes and are more restrictive than the default DevRev permissions, which allow all users to see everything. If you want the Jira AirSync permissions to take effect, the default policies must be removed.

Alongside permissions, groups and project roles referenced by the Jira project permission scheme are imported as well. AirSync roles are recreated on each sync run, so manual changes to these roles in DevRev may be overwritten on the next sync.

During the mapping phase of the initial import, you can opt out of permissions AirSync by deselecting the Authorization Policy option. Groups and group members can also be deselected. Because project roles are mapped to DevRev groups, deselecting groups and group members also prevents project roles from being imported.

📝 Note: Permissions AirSync is not supported for Jira Data Center.

Project import

To ease the transition from Jira to DevRev, you can import your Jira projects into DevRev. The project import is a one-time bulk import of a Jira project into DevRev. Once this import is complete, several options become available for that project, such as resyncing changes, syncing back to Jira, and bidirectional syncing.

Import a Jira project

📝 Note: The Jira AirSync snap-in must be installed in your workspace before you can configure a project import.

1. Go to Settings > Integrations > AirSyncs.

2. Select AirSync, or Start AirSync if this is your first.

3. Create a connection to a Jira site, or select an existing connection.

4. Once the connection is established, select the project you want to import.

5. Configure the Jira project import when prompted.

Set up the import recipe

A Jira project import is highly configurable. The configurations for a specific project import are referred to as the recipe. Key configuration areas are described below.

Work type to create in DevRev

You can import Jira issues as DevRev issues (the default, suitable for development work) or as DevRev tickets (suitable for customer request tracking). There is also an option to import Jira epics as DevRev enhancements, which is useful when epics represent large features or projects.

Jira issue types to import

Jira projects typically contain multiple issue types: epics, stories, bugs, and tasks are common. You can configure which types to import from Jira.

Field mapping

DevRev automatically maps your Jira fields to corresponding DevRev fields where possible. For fields that cannot be mapped automatically, you are prompted to specify the mapping during setup.

Sync from Jira to DevRev

After a successful import of a Jira project, the sync from Jira to DevRev option becomes available. This feature replicates issues created after the import and changes to previously imported issues.

To perform a one-time sync from Jira to DevRev, go to Settings > Integrations > AirSyncs, find the previously imported project, and select ⋮ > Sync Jira to DevRev.

⚠️ Warning: This sync overwrites work item fields in DevRev, even if those fields were changed in DevRev after the original import.

Sync from DevRev to Jira

After a successful import of a Jira project, the sync from DevRev to Jira option becomes available. This feature writes back any changes made in DevRev to previously imported issues. Additionally, any DevRev work item marked for sync to this project is created in Jira.

To determine which items are included in the sync, DevRev uses a subtype mechanism: each work item is assigned a subtype corresponding to the Jira project it should sync to. Only items carrying a matching subtype are written back to Jira. For full details on subtypes, see Subtype mechanism for 2-way sync.

To perform a one-time sync to Jira, go to Settings > Integrations > AirSyncs, find the previously imported project, and select ⋮ > ← From DevRev to Jira.

⚠️ Warning: This sync overwrites issue fields in Jira, even if those fields were changed in Jira after the original import.

Mark a DevRev work item for syncing

Marking with UI

Using the sync from DevRev to Jira feature, you can sync DevRev work items to Jira projects that have been imported into DevRev. A work item must be marked for syncing before it is included. Marking can be done during work item creation: open the Select Subtype dropdown, set it to the Jira project, and select the work item type to sync. The display format is {Jira project name} / issues / {type}. For example, to sync a bug to a Jira project called Maple, the entry appears as Maple / issues / Bug.

Marking with API

To mark an item for sync when creating it via the API, use the subtype name directly. The subtype format is _jira\_{jira\_site}\_{jira\_project\_name}\_issues.{type}_. For example, to sync a bug to a Jira project called Maple served through https://devrev.atlassian.net, the subtype is _jira\_devrev.atlassian.net\_maple\_issues.bug_.

After a DevRev work item is marked for syncing, it is created in the specified Jira project the next time the sync from DevRev to Jira runs. This can be triggered manually or automatically through a periodic sync. Subsequent syncs keep the item updated on both sides after it has been created in Jira.

Historical AirSyncs

To view running and previous AirSyncs from various sources:

1. Go to Settings > Integrations > AirSyncs.

2. Select the import you want to view.

3. Select ⋮ > View Report.

Periodic sync

After successfully importing a project into DevRev, you can enable periodic sync to automatically synchronize Jira data with DevRev on a recurring schedule. By default, the sync runs once an hour.

To configure periodic sync:

1. Go to Settings > Integrations > AirSyncs and locate the previously imported project.

2. Select ⋮ > Set Periodic Sync.

3. Configure the following options:

   • Jira → DevRev: Enable this option to sync data from Jira into DevRev on the selected schedule.

   • DevRev → Jira: Enable this option to sync data from DevRev into Jira on the selected schedule.

   • Enable automations for synced items: When enabled, created or updated items trigger webhooks, notifications, snap-ins, and other DevRev-native events for synced items. When disabled, periodic syncs do not trigger any events or automations. This behavior applies only to periodic syncs; no events are triggered during a first-time import or a manual sync.

4. Select the frequency and start date, then select Schedule to activate the periodic sync.

Delete import

⚠️ Warning: Deleting an import removes all content it created, including users and work items, even if that content was subsequently modified in DevRev.

An import and all the content it creates can be deleted from DevRev. This is useful when running proofs of concept or when you need to change the recipe used during the original import. After deletion, you can re-import the project from scratch.

If you need to update only a subset of items rather than delete and re-import the entire project, see Partial reimports for available options.

To delete an import and all the content it created, go to Settings > Integrations > AirSyncs, find the previously imported project, and select ⋮ > Delete Import.

Sync DevRev comments to Jira

Comments created under synced issues are automatically synced from DevRev to Jira when syncs are performed. These comments are posted under the name of the Jira user who authorized the connection, because the Jira API does not support creating comments as an arbitrary user. A special prefix is added to each comment to indicate the original author in DevRev and the timestamp of comment creation. Before posting, AirSync checks the Jira user's time zone and uses it to format the timestamp in the prefix.

The comment prefix format is: DevRev comment by John Doe on Jan 3, 2021 3:21pm

For information about threaded comment support, see Threaded comments.

Jira Data Center comment visibility

Jira Data Center allows restricting comment visibility to members of a specific project role. DevRev has no direct equivalent, so when syncing comments from Jira to DevRev, all comments are visible to all users who can see the issue. When Jira issues are imported as tickets, a visibility mapping can be configured during the initial import to control how Jira project roles map to internal or external comment visibility in DevRev.

For full details on comment visibility mapping, including reverse sync configuration, see Jira Data Center comment visibility.

AirSync Jira scope and limitations

The following limitations apply when performing a Jira AirSync. In addition to these Jira-specific limitations, see AirSync scopes and limitations for generic constraints.

Attachments

• Attachments on Jira comments are not transferred as comment attachments in DevRev. Because the Jira API returns attachments at the issue level only, they are transferred as attachments to the issue instead. For full details, see Attachment handling in AirSync.

Comments

• Syncing comment updates is not supported.

• Threaded and inline comments are not supported. Jira comments that are part of a thread or are inline annotations are imported as top-level comments in DevRev, without threading context. For more information, see Threaded comments in AirSync.

Connection

• The Jira Cloud user who authorizes the connection must be a site admin or organization admin for AirSync to collect user email addresses. Otherwise, Jira users are collected but created with generated email addresses. The DevRev admin can merge the user accounts manually.

• The Jira Data Center user who authorizes the connection must be a site admin or organization admin to access application roles, through which application users are collected.

• For Jira Data Center, the only supported connection type is PAT-based. When creating a PAT, you can specify an expiration date. For long-running migrations, set the PAT to never expire; if it expires, it must be recreated manually in Jira.

• For self-hosted Jira Data Center instances behind a firewall, the DevRev AirSync service IP ranges must be allowlisted before a connection can be established. See Firewall and self-hosted connector requirements for the required IP ranges and configuration steps.

Updates

• If a Jira field is not writable in the creation or edit screen, AirSync may fail to create or update the corresponding issue in Jira.

• If there is no direct transition from the current issue state to the target state in Jira, the state in Jira is not changed.

• Comments that originate in DevRev and are synced to Jira are not synced back to DevRev if they are subsequently edited in Jira.

Sub-tasks

• When creating a sub-task in DevRev, the creator must specify a parent issue in the parent field. The parent issue must also be of a synced Jira subtype. If the parent field is empty, the sub-task is not created in Jira and appears as failed in the report under the Issues column.

Epics → Enhancements

If you choose to import Jira epics as DevRev enhancements, the following limitations apply:

• A special enhancement subtype is created in DevRev for synced epics. Only DevRev enhancements of this subtype sync back to Jira as epics; other enhancements do not sync. Links to non-synced enhancements appear as errored in reports. If an issue is assigned to a non-synced enhancement and a reverse sync is performed, the issue is not assigned to any epic in Jira, and after the next forward sync the issue defaults to the default part.

• AirSync extracts all links related to synced items, including links between synced and non-synced items. Links to non-synced items are skipped, and the report shows them as skipped.

• In the forward sync, AirSync creates parent-child links from Jira parent fields; for example, a subtask with a parent task produces a parent-child link in DevRev. These links are skipped in the Jira loader because Jira has no equivalent parent link, and they appear as skipped in reports. Each such link is created only once per issue.

• Deleting and reimporting can produce dead links in DevRev that point to issues deleted in AirSync settings. These links do not appear in the UI but can be extracted and appear as failed in reports.

• Changing an epic to an issue after the corresponding enhancement is already created in DevRev removes the enhancement from the sync. All links pointing to that enhancement are skipped in the Jira loader and shown as skipped in reports.

• Setting an enhancement as the default part of the import is not supported when importing epics as enhancements, because enhancements cannot be linked together with an IsPartOf link. This can result in issues not being imported if their parts cannot be resolved.

Custom links

• All link types not imported as a custom link type in the current sync, and not belonging to the following list, are skipped in reverse syncs. Allowed stock links: is_dependent_on, is_duplicate_of, is_parent_of, is_related_to.

Permissions

• Supported permission holders are: project roles and their members, project lead, individual users, and groups and their members. Field-scoped permission holders such as assignee are not supported.

• A group named jira-software-users is used by Jira internally when the Any logged in user option is selected in the project permission scheme. This is the default name and can be renamed in Jira. If it has been renamed, AirSync cannot resolve which group corresponds to the Any logged in user option.

• Permissions are not AirSynced for epics mapped to enhancements. Permissions are imported only for issues and their subtypes.

Troubleshooting

• Issue: Users are created in DevRev with generated email addresses instead of their real Jira email addresses.

  Solution: The authorizing Jira Cloud user must be a site admin or organization admin. Re-authorize the connection with an account that has the required admin role, then merge the generated accounts with the real user accounts. See Merge user accounts.

• Issue: Custom stages in DevRev do not match Jira workflow statuses.

  Solution: Ensure the authorizing user has the Administer Jira global permission (and the manage:jira-project OAuth scope for Jira Cloud) so that workflow and workflow scheme extraction succeeds. If the permission cannot be granted, map stages manually in DevRev after import.

• Issue: A sub-task fails to create in Jira and appears as failed in the Issues report.

  Solution: Verify that the sub-task has a parent issue specified in the parent field and that the parent issue is of a synced Jira subtype.

• Issue: Reverse sync fails to update a field in Jira.

  Solution: Check that the field is writable in the Jira issue creation and edit screens. Fields that are read-only or hidden in those screens cannot be updated by AirSync. Also verify that the authorizing user has the Edit Issues permission for the project.

• Issue: AirSync cannot connect to a self-hosted Jira Data Center instance.

  Solution: Ensure the DevRev AirSync service IP ranges are allowlisted in your firewall. See Firewall and self-hosted connector requirements.

• Issue: The PAT used for a Jira Data Center connection has expired, and syncs are failing.

  Solution: Generate a PAT in Jira with no expiration date (or a sufficiently long expiration) and update the connection credentials in DevRev AirSync settings.