Promoting configuration changes from staging to production
Tasks described on this page are not native to Jira. To complete them, you’ll need to install a 3rd party add-on Project Configurator for Jira.
- Developing and validating changes in staging
- Exporting configuration for changed projects from staging
- Importing project configuration into production
- Verifying results of promotion
What do we mean by "promoting configuration changes from staging to production"?
Let us explain with an example. Imagine you are the Jira administrator in charge of a Jira instance with a few hundred users. The users working in two of the biggest projects want to implement changes to how those projects are managed in Jira. The Jira team knows that implementing those changes needs at least three days of work, and also that they should be reviewed and validated by the users before putting them in production. Some of the user requirements are not absolutely clear and you know that until users see the implementation they will not be able to decide if that new implementation is what they actually need. A preliminary analysis of the requirements has shown that they imply changes to project workflows, screens, custom fields, and permission schemes. New groups will also be created so that permissions can be granted only to those users that need them.
Starting to implement these changes on production means Jira users would have to put up with three days of partially implemented changes. What's more, the changes won't be final until the users validate them, so it is possible they have to be modified and redone a few times. This would mean massive disruption to everyday work for users in the affected projects. So you quickly realize that those changes must be implemented first in a separate development instance (which we will call "staging" in this guide.)
This decision brings up new questions:
- How to migrate the changes implemented in staging to production without manually redoing them?
- How to make sure the tests and validations in staging really represent the final result when the changes are moved into production?
This guide intends to answer these questions, offering a recommended process for implementing, reviewing, and promoting configuration changes between Jira instances. This process is based on the use of the plugin called Project Configurator for Jira.
A more elaborate process
In some cases, when the rate of changes applied into production is very high with frequent configuration updates for different projects, the process described in this guide might not guarantee a representative test of the new configuration impact on production. In these cases, it would be practical to have a variation of the process that uses an additional Jira instance.
In this variation, when changes are ready to be applied to production, a clone of production is created. Let's call this clone "pre-production". Changes are imported into pre-production and the new configuration is validated there, eventually fixing anything if necessary. Then, the new configuration for the changed projects is exported from pre-production and imported into production.
Obviously, the import into pre-production does not require the same caution as into a real production instance, so a previous backup and locking up the instance would not be needed.
What is included in the concept of "configuration"?
The best way to explain it is pointing to the list of entities that Project Configurator for Jira will move in a configuration export/import.
When you export the configuration for a group of projects, all configuration objects that are used by those projects will be exported. For more information, see Selection of objects to export.
Technical limitations are described here. Note that the limitations in the items that must coincide in both Jira instances section would not be an issue if the advice in this guide is followed. Starting with the staging instance as a clone of production would guarantee that those aspects of both instances are the same.
Cloud and Server instances
The process explained in this guide is valid only for Jira Server instances. If you want to use it for promoting changes into a Jira Cloud instance, you could only do it indirectly by following these steps:
- Clone a Jira Cloud instance into a Server instance that will be used as a staging machine (for development and test.) This would replace the first step explained in the guide.
- Follow the rest of steps as explained in the guide, up to and including exporting the configuration changes from staging.
- Lock the Jira Cloud instance to users.
- Clone it to a Jira Server instance. This will act as the "production" instance in the next steps of the process: importing configuration and verifying results.
- When verification shows that promotion results are correct at the "production" Server instance, move it to the Cloud, replacing the previous Cloud instance.
- Open the new Cloud instance to users and resume normal work.