Scenario

You are a Jira administrator and get a configuration change request by a stakeholder to add a new workflow, add new custom fields, change screens, etc. You’ve created and tested these configuration changes on a Test or development Jira instance. 

Now, you want to apply the same changes to the Production Jira instance, but before that, you want to make sure these updates won’t cause errors or disruption of the end-user experience in Production.

How CMJ solves this challenge

Configuration Manager for Jira (CMJ) was designed to give the best solution in this scenario. It allows Jira administrators to save time and achieve secure and effective change management by automatically transporting Jira projects from Test through Staging to Production Jira instances.

Implementing the Test-Staging-Production use case goes through a few major phases:

• Setup: Setting up the Test and Staging Jira instances.  

• Phase 1: Configuring proposed changes on the Test Jira instance.

• Phase 2: Testing the configuration changes on the Staging Jira instance.
  Creating a CMJ project snapshot with the changes on the Test instance and deploying the snapshot on the Staging Jira instance to verify the changes.

• Phase 3: Deploying the configuration changes on the Production Jira instance.
  Creating a project snapshot on the Staging instance and deploying the snapshot on the Production instance.

Video guide

See the Test-Staging-Production use case in action in this video showing how to perform change management tasks in JIRA with CMJ.

Use case steps

This section will guide you through the steps of implementing the Test-Staging-Production use case.

High-level process

This part guides you through each of the Test-Staging-Production use case phases:

• Setup: Setting up the Test and Staging Jira instances. Learn more 

• Phase 1: Configuring proposed changes on the Test Jira instance. Learn more

• Phase 2: Testing the configuration changes on the Staging Jira instance. Learn more

• Phase 3: Deploying the configuration changes on the Production Jira instance. Learn more

Review the diagram and follow the detailed guide below to make the desired configuration changes and improvements to your production Jira instance reliably and safely.

Open

Prerequisites and use case elements

This section presents and illustrates key points and elements of the Test-Staging-Production use case.

Duration	Setup	Snapshot type	Deployment mode	Automation
Open < 10 minutes	3 Jira Servers	Project Snapshot	Project Merge Mode	REST API Support

• 3 Servers are required: Test, Staging, and Production Jira instances. The Staging server should be an identical or close replica of the Production server.

• Make sure the same version of CMJ is installed on all instances. If not, the version on the staging and production instances should be more recent than the test instance.

• You need one paid CMJ license for the production Jira instance and two free developer CMJ licenses for the test and Staging Jira instances.

• Make sure CMJ supports the Jira configuration objects you would like to configure. Supported objects and integrated apps are listed in our Support Matrix and List of Integrated Apps articles.

• Any apps used to configure objects in the test instance must also be installed on the staging and production instances, ensuring the app versions are the same.

• It is suggested best practice that your Jira versions of the test, staging, and production instances be the same.

• CMJ loads configuration and dependencies and performs analysis in memory, so you should allocate sufficient resources depending on the Jira instances. We recommend following Atlassian’s Jira sizing guide.

Detailed process

Follow the detailed steps listed here to implement the Test-Staging-Production use case in your environment.

Setup

• Create Test and Staging Jira servers if they don’t exist already. Later, you’ll use Configuration Manager to clone the Production environment to these two additional servers. The Staging server must contain all the project configurations and issue data from Production. Still, you can set up the Test server with just the project configurations from Production containing configuration changes (without the rest of the projects and the Jira issues). This way, you’ll be able to build the testing environment in minimum time.

• Install Configuration Manager on each of the servers and set up their licenses. You’ll need a production (paid) license on your production server, and you can use free development licenses on the Staging and Test instances. See our Licensing Options for more information.
  
  

Phase 1: Configuring а proposed change on Test

1. Test instance: Make the desired/proposed changes to the projects in question. The reason for making the changes in the testing environment is because depending on the number and complexity of the changes, it may take you a while to set all projects and issues up and confirm it’s working as expected. 

2. Test instance: Test the functionality to ensure the planned change is working as expected (i.e., test workflow). The actual testing depends on the complexity and range of your changes and may include creating issues, exercising issue workflows, etc.
   
   Phase 2: Testing the configuration change on Staging

3. Test instance: Create a project snapshot of the changed project(s). Learn more about creating a Project snapshot.

4. Staging instance: (recommended) Create a system snapshot of the Staging Jira instance for backup purposes if you want to test new configuration changes later.

5. Staging instance: Deploy the project snapshot to your staging environment. Learn more on how to deploy CMJ configuration snapshots.

   1. Use the Project Merge mode when deploying the snapshot.

   2. Review the change and impact analysis in the analysis step of the deployment. At this point, you will get an understanding of how the deployed configuration will impact the Production server since Staging is a current clone of Production.

   3. Warnings or errors might appear at this stage. Resolve the errors to proceed with the deployment.

   4. Once errors are cleared and everything looks okay on the analysis step, proceed with the deployment.

      The deployment might end successfully, fail, or end with warnings. In case of a deployment failure or warnings, we recommend reviewing the Audit log for more details. It will contain information on all errors and warnings encountered during the deployment.

   5. Get stakeholders involved in User acceptance testing on this phase to confirm the proposed changes are operating as expected (i.e., test workflow). The actual testing depends on the changes you made and may include creating issues, exercising issues workflow, etc.

6. Test instance: If the desired change is not causing the expected behavior or not working, locate the error and make changes in the test environment to address it.

7. Staging instance: Then restore the Staging server with the System snapshot created in step 2 above to prepare this environment for testing the corrected configuration changes.
   We advise you not to make changes directly to the Staging server. It needs to remain the same as Production to ensure the desired end-user behavior for further tests on staging.

8. Staging instance: If the deployment on the Staging Jira instance is successful, there are no errors, and the changes are causing the desired end-user behavior, continue with the deployment to Production.
   
   Phase 3: Deploying the configuration change on Production

9. Staging instance: Create a project snapshot of the project(s) with the updated configurations.

10. Production instance: (recommended) Create a system snapshot for backup.

11. Production instance: (recommended) Limit the user access to Jira. We advise you to make all changes to production servers only during maintenance windows when user access is limited.

12. Production instance: Deploy the project snapshot. Learn more on how to deploy configuration snapshots.

    1. Use Project Merge mode.

    2. Review the change and impact analysis in the analysis step of the deployment. Since you tested the changes on the Staging server, the change and impact analysis shown at this step should be identical to the one on Staging.

    3. If the change and impact analysis are different from the one on Staging, then the two environments are different and should be mirrored again.

    4. If the change and impact analysis shows that everything is okay, proceed with the deployment.

    5. The deployment might end successfully, fail, or end with warnings. In case of a deployment failure or warnings, we recommend reviewing the Audit log for more details. It will contain information on all errors and warnings encountered during the deployment.

    6. If the deployment completes successfully without errors, open the system to all users.

    7. In case of a deployment failure, restore the Production server with the system snapshot created at step 2 above. Then, restart the process from the beginning. 

13. If the Staging server is identical to the Production, there shouldn’t be any failures.
    We advise you not to make changes directly to the Production server(s). Always test the planned changes on the staging environment first and then apply them to your production environment.

Tips & Tricks

This section aims to present you with CMJ’s invaluable features, tips, and tricks that will help you track, secure, and automate moving Jira configurations between instances.

Review projects affected by a change

Affects N projects label on the Analyze Configuration Changes step shows the projects affected by deploying the current configuration change. For more details see the Review Affected Projects section here.

Audit logs

You can download and keep the audit log even on successful deployment, as the log file can serve as a document/history of what has been changed on the system during the deployment. Then, if needed, you can present this information to the relevant stakeholders or attach it to the issue in your issue tracking system as a log of the work done.

Rollback of the deployment

Configuration Manager (CMJ) supports rollback of configuration changes if anything goes wrong during the deployment. This means that if an unexpected error happens while applying a change, CMJ will automatically roll back all configuration changes applied until that moment.

Automation and API

You can automate this use case using our public REST API.