Server/Data Center to Cloud Step-by-step Migration Guide

In this page

Step-by-step guide

This section provides a step-by-step guide to help you migrate your Better Commit Policy for Jira configuration from Server/Data Center to the Cloud version.

It assumes that you already understand the differences between the source and target versions. It also assumes that you have administrator access to both.

Step 1: Define your target

Before you begin the migration, define the target configuration you want to achieve in the cloud. This clarity will guide your decisions and ensure each migration step moves you toward the intended end state.

As part of this definition, plan how you want to check the changes in your repositories. Then define your conditions (requirements for commit message format, links to work items, etc.), rejection messages, and when to skip checks.

Steps:

1. Review the cloud documentation. In particular, get familiar with the configuration options available in the Cloud version.
2. Analyze your current Server/Data Center commit policies. (You can also use this migration as an opportunity to review and improve your developer workflows.)
3. Plan your cloud migration in theory, without making changes yet:
   • Define how to convert your current Server/Data Center commit policies to the .commitpolicy.yml configuration file used in the Cloud version.
   • Check out the tutorials for extra guidance.

Step 2: Get started with the Cloud version

Install the Cloud version of the app and verify it works correctly with the defaults before migrating custom configurations.

Steps:

1. Install the Cloud version.
2. Follow the getting started guide.
3. Don't proceed until the app works with the defaults (in at least one repository).

Step 3: Migrate your commit policies

In the Server/Data Center version, commit policies are defined once and multiple repositories can use the same shared configuration. In the Cloud version, commit policies follow an "x-as-code" model, where each repository has its own .commitpolicy.yml configuration file.

Because of this, you can migrate repositories one by one, rather than all at once, allowing you to transition gradually at your own pace.

Migrate the commit policy for a repository

This section guides you through migrating the commit policy for a single repository. It assumes the repository has already been migrated to the Cloud.

It is essentially about adding the .commitpolicy.yml configuration file to the Cloud repository, which implements a commit policy equivalent to your Server/Data Center policy. Important: you only need to do this for your blessed repositories, as forks and local clones will automatically receive the file at their next sync.

Steps:

1. Find your VCS connection ID (you'll need this later):
   1. Open your Jira Cloud site (in a browser tab).
   2. On the Jira interface, go to Apps (in the left-bar) → Better Commit Policy.
   3. In the Connected VCS workspaces box, find your Bitbucket Cloud workspace.
   4. Click the icon to copy the connection ID to the clipboard.
   5. Close the tab.
2. Add the policy configuration file in Bitbucket Cloud:
   1. Open your Bitbucket Cloud workspace (in another browser tab).
   2. Navigate to the repository, open Source.
   3. Click the "..." button → Add file.
   4. Enter .commitpolicy.yml as filename.
   5. Copy this to the file content (but don't commit it yet!):

      commit-policy:
        name: "..."
        description: "..."
      vcs-connection:
        id: "..."
      commit:
        # ... migrate commit conditions over here
      pull-request:
        # ... migrate branch conditions for pull request source and destination branches here
      setting:
        # ... migrate global settings over here
      

   6. At line 5, replace "..." with the VCS connection ID with the value you just copied to your clipboard. (Be sure to preserve the brackets!)
   7. Migrate the commit policy settings to the configuration file:
      1. Open the Server/Data Center commit policy for editing (in another browser tab). If you don't have write permission, viewing it in read-only mode is sufficient. Keep it open as a reference while you create the equivalent settings in the Cloud.
      2. At line 2, replace "..." with the name copied from the Server/Data Center commit policy.
      3. At line 3, replace "..." with the description copied similarly.
      4. Configure the fields in the commit:, pull-request: and setting: sections to match your Server/Data Center settings. As there isn't always a direct one-to-one match, we compiled a mapping table to help. If you can't or don't want to migrate something, just skip it. It can be added any time later.
   8. Commit it.
   9. Close the tab.
3. In the repository, open Commit policy.
4. The Commit policy screen will display the parameters. (In case of validation errors, see the troubleshooting guide).
5. Make sure that the "Commit Policy Satisfied" custom merge check is enabled in this repository.
6. Test the migration by viewing the merge check results for two pull requests:
   1. Negative test: find a pull request with an incorrect title or problematic commits, and verify that the merge check reports an “N violations” status.
   2. Positive test: find a clean pull request with no problems, and verify that the merge check reports a “Satisfied” status.
7. You're done!

Server/Data Center to Cloud settings mapping

The table below shows how Server/Data Center settings correspond to Cloud configuration fields, helping you set up an equivalent commit policy. For all available options, including additional Cloud-only settings, see the Configuration reference.

Server/Data Center setting	Cloud configuration field	Notes
Commit policy settings
Commit policy name	commit-policy.name	You can simply copy over the text.
Commit policy description	commit-policy.description	You can simply copy over the text.
Rejection message	*.rejection-message	You can simply copy over the text.
(Re-)verify already existing commits
Verify merge commits	commit.type.skip-merge	The field value is reverse: if the setting is turned on, set the field to false.
Tag conditions
Tag name must match a pattern	Not available yet	This feature is on our mid-term roadmap.
Tag name must contain issue keys from a JQL query	Not available yet	This feature is on our mid-term roadmap.
Branch conditions
Branch name must match a pattern	pull-request.source-branch.pattern pull-request.destination-branch.pattern
Branch name must contain issue keys from a JQL query	pull-request.source-branch.work-item.* pull-request.destination-branch.work-item.*
Commit conditions
Commit message must match a pattern	commit.message.pattern
Commit message must contain issue keys from a JQL query	commit.message.work-item.*
Changed paths (files) must match a pattern	Not available yet	This feature is on our mid-term roadmap.
Changed paths (files) must contain issue keys from a JQL query	Not available yet	This feature is on our mid-term roadmap.
Committer must have a valid Jira account"
Committer attribute must match a pattern
Global settings
Issue key pattern for commit messages	setting.work-item-key-pattern
Issue key pattern for branches, tags and paths	setting.work-item-key-pattern
Bypass patterns	commit.message.skip-pattern pull-request.title.skip-pattern pull-request.description.skip-pattern pull-request.source-branch.skip-pattern pull-request.destination-branch.skip-pattern pull-request.commit.message.skip-pattern pull-request.commit.author.skip-pattern

Step 4: Explore new features

Embrace the full potential of the Cloud version with the new cloud-only app features:

• Pull request merge checks (with detailed results)
• Pull request conditions (title, description, source and destination branches)
• Dry run (encourage the policy without enforcing it)
• Recipes (a large library of common conventions)
• Merge checks at workspace, project, and repository levels (three scopes)

Questions?

Ask us any time.