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 Cloud.

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 commits, puill requests and other 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. You can always add it 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 Not available yet This feature depends on whether push checks are technically feasible.
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 		You can already check the names of source branches and destination branches of pull requests. Plus, a check for newly created branch names is on our mid-term roadmap.
Branch name must contain issue keys from a JQL query pull-request.source-branch.work-item.*
pull-request.destination-branch.work-item.* 		You can already check the work item keys in the names of source branches and destination branches of pull requests. Plus, a check for newly created branch names is on our mid-term roadmap.
Commit conditions
Commit message must match a pattern commit.message.pattern You can simply copy over the pattern.
Commit message must contain issue keys from a JQL query commit.message.work-item.* You can configure the equivalent condition behavior using the three fields: jql, count, and non-matching.
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" Not available yet This feature is on our mid-term roadmap.
Committer attribute must match a pattern Not available yet This feature is on our mid-term roadmap.
Global settings
Issue key pattern for commit messages setting.work-item-key-pattern You can simply copy over the pattern.
Issue key pattern for branches, tags and paths setting.work-item-key-pattern Note that currently there is a single pattern which is used to parse work item keys from all text pieces. You can already check the work item keys in the names of source branches and destination branches of pull requests. Plus, a set of checks for newly created branch names, tag names and paths is on our mid-term roadmap.
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 		You can skip checks using slightly different settings. Some areas have been extended, while others are more limited. (A few options were removed good reason. let us know if you miss anything!)

Step 4: Explore new features

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

Questions?

Ask us any time.