Merge Jira Servers [archived]


This document describes best practices recommendations for moving projects between Jira server instances. The described approach can be used for consolidating efforts such as merging multiple Jira instances.

For this document, we'll assume the following definitions:

  • Development: a free-for-all one or many environments where users can play with cutting-edge or risky changes.

  • Staging: a pre-production environment, where the systems administration team can establish exact procedures prior to rollout. The staging should be clone or close replica of the production environment. 

  • Production 1 (Source): your live instance where the project(s) originate, expecting minimal downtime and well tested changes.
  • Production 2 (Target): your live instance where the project(s) should be moved, expecting minimal downtime and well tested changes.
  • Configuration snapshots are created using Configuration Manager for Jira app and represent the state of your Jira configuration objects and their relations to each other at a given point in time. There are two types of configuration snapshots:
    • Project snapshot: contains the configuration of a number of selected projects (with their schemes, workflows, fields, etc.).
    • System snapshotcontains the entire configuration of a single Jira instance (projects, workflows, schemes, screens, etc...).

I. Architecture Strategy Recommendations

The moving of projects between Source (Production 1) and Target (Production 2) instances will result in modifications for your Target (Production 2) instance, so we'd recommend you follow the Test -> Staging -> Production procedure. Before starting the procedure, a signigant analysis should be performed - these activities are grouped in a separate phase called Analysis. The major difference between the process of moving projects and rolling-out configuration changes is that in the first case scenario all user-generated data needs to be transferred, which requires a significant up-front analysis. The process of moving multiple projects between Jira instances is comprised of four major stages:

  • Analysis - during this stage an analysis of the conflicts and gaps between the project configurations is performed captured in Application Migration Specification document.
  • Development - during this stage Migration Procedure document is developed and tested in test server.
  • Staging - during this stage the Migration Deployment procedure is staged and tested in staging server,
  • Production - during this stage the migration deployment procedure is executed in the official production environment.

II. Planning

All planning steps described in the Test-Staging-Production procedure use case should be completed:

  • Prepare the staging environments & keep them synchronized 
  • Install Configuration Manager for Jira
  • Track changes with change request tickets
  • Plan disruptive & non-disruptive changes during maintenance windows 
  • Prepare communication strategy 

Additionally, you should include the following planning steps: 

  • Prepare backup of both production servers 
  • Assess the health of both source and target instances and fix the detected issues. System health assessment should be performed with Jira Integrity checker and Configuration Manager for Jira Integrity Check.

III.  Stages

First Stage - Analysis

Overview of the first stage:

Jira Instances: Production 1 (or a clone), Test Server (clone of Production 2)
Goals: Prepare Application Migration Specification (AMS) document
Jira System Administrator, AD admin, DBA.
Tools Required: Configuration Manager for Jira

Below is the list of recommended analysis. If the they outline any changes that needs to be made, the changes should be included in the AMS document:

  1. Apps and Versions

    Both Prod 1 and Test Server meet the following requirements:

      • Running the same Jira version
      • Have the same set of apps with matching versions

  2. User Management Normalization

    If both production servers are using the same external user directory there should be a 100% match between the users and groups on both serves. If this is not the case, an analysis should be performed to identify gaps and conflicts. 


      1. Gap: On Prod1 Jane Smith has username jsmith, while on Prod 2 server her username is jane.smith
      2. Conflict: Both servers have user John Smith with username jsmith, but the usernames correspond to two different people

    Similar issues apply for user groups.

    Typically, the list of conflict and potential matches should be prepared and then the business users provide information how to resolve it.


    If the user management is not normalized a wide range of negative effects will take place. All fields where users or groups are used - Assignee, Reporter, etc. might contain wrong user or group. All configuration objects with users or groups could end up improperly configured - permissions, notifications, workflow customization with users and user group fields, filter and dashboard ownership, Agile board administrators, JQL filters with users or user group fields, issue security schemes etc.

    How to resolve gaps and conflicts
    The general approach for both gaps and conflicts is to rename the username either on the Prod 1 or Prod 2 servers to ensure consistency. The renaming depends on the solution used for user management Crowd, AD, LDAP.

  3. "As is" strategy

    In most cases the issues and project configuration are moved to the new production server "AS IS" without any modifications. Modifications will need to be transformed to ensure consistency on both Jira instances - this process will ultimately add significant complexity and time to the migration and should be included in the AMS document. For this guide an "As Is" strategy is used. For more information on the migration process with transformations, contact Botron's service team.


    The issue type Bug might be part of different workflows on the two server instances. When you move a project with that issue, the users have to choose between one of two options - in the "As is" case, the various projects use different workflows for the same issue type, while in the transformation case the two projects will use the same workflow, thus all the source data will be transformed to match the new workflow.

  4. Configuration Conflicts and Gaps

    When migrating projects their names or keys might already exist in the Prod 2 server, this conflict should be resolved by renaming them on the Prod 1 server. The same can happen for custom fields, resolution, priorities, workflow names and schemes. The full list of conflicts and the mappings of their resolutions should be included in the AMS document. The reverse scenario is possible too, when two custom fields on Prod 1 and Prod 2 have different names, but the same semantics. In this case, they ought to be merged during the migration.


    1. This analysis of these configuration conflicts and gaps can be performed by using the Configuration Manager for Jira change and impact analysis feature. Prior to migration, the Configuration Manager for Jira enables you to perform a change and impact analysis and provides you with a comprehensive details regarding the impact of the changes that will be applied to your Jira instance. By performing this analysis, you will be able to see the projects that will be affected by the change, identify any conflicts and gaps and resolve them. The list of introduced changes and their corresponding conflicts and gaps are grouped in tabs in the same logical order of a Jira menu.

    2. This analysis is great opportunity to optimize the usage of custom fields and reuse them between the two system, instead of creating new ones. This will greatly improve the performance of the server.

  5. Default Schemes

    Any default schemes used on the Prod 1 server by the migrated projects should be changed. To change the default schemes, perform the following steps: 
    1. Copy the used default scheme 
    2. Rename the newly created scheme.
    3. Associate the project(s) with the new scheme
  6. Quality Strategy

    Quality strategy should be developed and agreed upon by all stakeholders. The recommended quality strategy consists of test plans for each of the phases, as well as a post migration remediation plan.
  7. Test Plans

  Development phase a set of tests should be executed to verify the following:

  1. Filters - number of issues, issue ordering, column layout
  2. Dashboards - layout (columns, rows), gadgets & gadget content
  3. Agile
    1. Board views (i.e. backlog, active sprints)
    2. Issues, ranking, epics, versions, estimates, time tracking data aggregations
    3. Quick filters 
    4. Sprints ordering & content
    5. Reports
    6. Project <-> Board associations
  4. Issues
    1. Agile data - sprints, epic links
    3. History
    4. Field values - 3-rd party custom fields, time tracking and estimates, other
    5. Issue links
    6. Confluence links
    7. Bitbucket links (branches, commits)
  5. Security
    1. Projects - role memberships, access and operations for different roles
    2. Boards, Filters and Dashboards - ownership and operations
  6. Operations - transition through workflow, create/deleted/edit issues, comments ,etc.

Staging phase - the tests from the development phase are executed again and an User Acceptance Test (UAT) is performed by the users of the projects that is being migrated.

Production phase, a subset of the development phase tests are executed plus a limited UAT test. Typically, there is a time limit on how long can these test be performed in production. This time limit is aligned with the duration of the maintenance window during which the production phase takes place.

Post Production Remediation Plan - this plan covers the procedures designed to handle any post-migration issues that occurred during the production. It includes a SLA for response and resolution. 

Second Stage - Development

Overview of the second stage:

Jira Instances: Clone of Production 1, Test Server (clone of Production 2)
Goals: Prepare Migration Procedure document
Users: Jira System Administrator, AD admin, DBA.
Tools Required: Configuration Manager for Jira

The development stage is the most complex and time consuming.The steps of this stage are as follows:

Each of the migration tasks should be properly documented and in an ordered list. It should include any input data and enough details that it can be repeated consistently.
The recommended approach for documenting is a structure of tasks and steps to accomplish each task.

  1. For each of the data or configuration changes included in the AMS document, execute the required steps.
  2. Create project snapshot that includes the projects that are being migrated from Prod 1 server. Include all related to the projects Agile boards, filters, dashboards and issues (issue data support is supported since release 5.0 of Configuration Manager).
  3. Download the configuration snapshot  (if your Jira configurations are being tracked via tickets, the snapshot should be attached to the appropriate tickets.)
  4. Deploy configuration snapshot to Test Server and validate proposed configuration changes.
  5. It is crucially important to validate that the proposed configuration changes and impact match the AMS.
    1. If they don't match AMS, the changes made in step 2 need to be corrected. Restore your backup on the clone of Production 1 and the Test Server and resume from step 1.
    2. If they match AMS - continue.
  6. Update the ticket with the required deployment time for the snapshot deployment.
  7. Execute the test plan for test stage
    1. If the tests fail, they have to be resolved. Depending on the nature of the errors resolutions vary - changing the configuration steps (step 1) or contacting Botron's support team. Restore your backup on the clone of Production 1 and the Test Server and resume from step 1.
    2. if the tests pass then attached the Migration procedure to the migration ticket and proceed to Stage 3.

The steps described in this stage ought to be repeated several times to ensure that everything runs smoothly and both the proposed changes and the associated tests are successful. 

Third Stage - Staging/QA

Overview of the third stage:

Jira Instance: Production 1 (or a clone), Staging Server (close replica of Production 2)
Goals: This is the grand rehearsal of the migration and has two major goals:

  1. Verify the migration procedure and conduct an UAT.
  2. Get an accurate time estimate for the duration of the migration.

Users: Jira System Administrator, AD admin, DBA, business users to conduct UAT.
Tools Required: Configuration Manager for Jira

The steps of this stage are as follows:

  1. Execute each of the tasks from the migration procedure without any modifications.
  2. Estimate the required downtime.
  3. Perform development stage tests.
  4. Perform the UAT tests.
  5. If both the development phase test and the UAT are successful, declare successful staging and proceed to production.
  6. In case of failure, depending on the type of issue(s), either change the deployment procedure and repeat the staging or go back to development phase to correct the issue(s).

Fourth Stage - Production Deployment

Jira instance: Production 1, Production 2
Goals: Finish the migration in the official Production 2
Users: Jira System Administrator, AD admin, DBA.
Tools Required:  Configuration Manager for Jira

The fourth and final stage of the migration process is, for the most part, identical to the staging stage. The major difference being that you'd be working with the actual Production 1 and 2 servers, not their clones.

The steps of this stage are as follows:

  1. Create full backups of both production servers.
  2. Restrict the user access to Production 2 server.
  3. Execute each of the tasks from the migration procedure as they are captured without any modifications.
  4. Execute development stage tests.
  5. Execute the UAT tests.
  6. If both the development phase test and the UAT are successful, declare successful migration and open the access for the users.
  7. If not successful, depending on the type of issues found there are two options:
    1. Apply changes/fixes to Production 2 server and rerun the UAT tests.
    2. Restore the backups and reschedule the production deployment until the issues are resolved.

IV. Limitations & Workarounds

There are certain system limitations that need to be considered:

  • Apps data: Certain app custom field configuration, app workflow property configuration any other app data outside of Jira configuration objects might not included. A custom solution needs to be developed.

Suggested workarounds regarding limitations and other known issues include:

  • Scripts - API level scripts can be developed to migrate any data not handled by Configuration Manager for Jira. Great choice for scripts development is using the ScriptRunner app.
  • Manual - If the amount of configuration is not extensive it can be manually added to the target Jira.
  • Professional Services -  Botron's team of solution architects can develop custom solution that migrates any type of data.

V. Frequently Asked Questions

  1. Is my entire configuration and all the issues are going to be moved to production automatically using Configuration Manager for Jira?
    Yes. The entire configuration, captured in the configuration snapshot, will be rolled-out. All the issues to the selected projects as well. Some apps configuration and data which are not supported by Configuration Manager for Jira won't be moved. The supported objects are listed here.
  2. Can I move projects from a server with a newer server instance to an older server instance?
    It is strongly recommended that both production servers are on the same version. The opposite adds unnecessary complexity.
  3. How long does it take to move multiple projects?
    Depending on the user management normalization, the amount of data and the other analysis, it can take anywhere from several hours to few weeks.
  4. Can custom apps data be moved using Configuration Manager?
    Yes. Configuration Manager can be extended to handle any custom apps. Contract Botron's services team for more information.

VI. Need Help?

If you cannot resolve the problem yourself, you can contact us for assistance via the following communication channels