Get started

In this page

Get started with commit policies

This page has two main sections:

1. The Administrator guide covers the essential setup steps an admin needs to complete before users can start using the app.
2. The User guide provides developers with simple, step-by-step instructions on the app's key features.

Take a few minutes to go through these guides, they'll help you get up and running smoothly!

💡 Tip: the app offers a built-in onboarding experience that implements this guide in an interactive, guided way. Click the Get started button on the Commit Policy screen to start it. It covers both guides, except for step 1 of the Administrator guide (which is a one-time setup step).

Administrator guide

Don't worry if this guide looks long or complicated - it's absolutely not! Most of these steps only need to be done once, usually when you're just getting started.

Note: different steps may require different permissions, which will be clearly indicated.

Step 1: Connect your Bitbucket workspace to your Jira site

(estimate: 2 min, requires Bitbucket administrator and Jira administrator permissions)

The VCS connection (a secure connection between Jira and your Version Control System) only needs to be set up once when you're getting started. You'll only need to do it again if you add another Jira site later on.

Steps:

1. Go to your Bitbucket workspace.
2. Install the Better Commit Policy Connector for Bitbucket app to the Bitbucket workspace (if it is not already).
3. Go to your Jira site.
4. Install the Better Commit Policy for Jira app to the Jira site (if it is not already).
5. On the Jira interface, go to Apps (in the left-bar) → Better Commit Policy.
6. Click Connect a VCS workspace now (on the top).
7. Create the VCS connection:
   1. Click Add VCS connection.
   2. Select Bitbucket as VCS hosting service.
   3. Enter your Bitbucket workspace URL.
   4. Click Save.
8. Click the workspace URL in the table. (Bitbucket opens in a new browser tab, but keep Jira open, as well.)
9. The VCS connection is successfully created! ✅

Step 2: Enable custom merge checks for the workspace

(estimate: 30 sec, requires Bitbucket administrator permission)

A Bitbucket admin must enable custom merge checks for the entire workspace. Note that if there is at least one repository in the workspace using custom merge checks, you can safely skip this step, as it's already done.

Steps:

1. Click the browser tab that shows your Bitbucket workspace.
2. Go to Workspace settings (cog icon "⚙" in the top right) → Custom merge checks.
3. Click Enable. (If you can't see the button, it is already enabled.)
4. Custom merge checks are enabled! ✅

Step 3: Add the merge check to a repository

(estimate: 30 sec, requires repository administrator permission)

A repository admin must enable the custom merge check in a specific repository to check if pull requests targeted to that repository comply with the commit policy.

Steps:

1. Go to the repository → Repository settings (cog icon "⚙" in the left-bar) → Custom merge checks.
2. Click Add check at "Better Commit Policy Connector for Bitbucket".
3. Select the "Commit policy satisfied" check.
4. Select "All branches".
5. Check "Required". (It is a Bitbucket Premium-only feature. On other plans, skip it.)
6. Save it.
7. Merge check is now added! ✅

Step 4: Add the commit policy to the repository

(estimate: 3 min, requires repository write permission)

You're about to add a starter policy that ensures each commit message and pull request title includes a valid Jira work item key, and that pull request descriptions aren't left empty. This helps keep every change clearly linked to its Jira work item.

Steps:

1. Find your VCS connection ID (you'll need this later):
   1. Go back to your Jira site (should still be open in another 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 workspace.
   4. Click the icon to copy the connection ID to the clipboard.
   5. Close the tab.
2. In the Bitbucket repository, click Apps → Commit policy.
3. Select the branch on the top which you want to add the commit policy configuration file to. (Typically the main branch, or another actively used branch that everyone frequently syncs with.)
4. Click the yellow Settings button on top right.
5. Click Add next to the .commitpolicy.yml resource. (The button is enabled only if the configuration file is missing.)
6. Confirm it by clicking Add.
7. Click View next to .commitpolicy.yml to open it in a new browser tab:
   1. Click Edit.
   2. At line 6, replace "<connection-id>" with the VCS connection ID you just copied to your clipboard. (Be sure to preserve the double quotes!)
   3. Commit it.
   4. Close the tab.
8. Close the Commit policy settings dialog.
9. The Commit policy screen will reload and display the parameters. (In case of validation errors, see the troubleshooting guide).
10. The initial commit policy is successfully added! ✅

Step 5: Add the local check hook script to the repository

(estimate: 30 sec, requires repository write permission)

Local checks require adding a dedicated hook script to the repository. Once it's committed, every developer who syncs with the repository will have it available automatically — no manual distribution needed.

Steps:

1. In the Bitbucket repository, click Apps → Commit policy.
2. Select the same branch that you selected in step 4.
3. Click the yellow Settings button on top right.
4. Click Add next to the commit-msg hook script resource. (The button is enabled only if the script is missing.)
5. Confirm it by clicking Add.
6. Close the Commit policy settings dialog.
7. The repository is ready for local checks! ✅

🎉 The app is ready to use! Follow the User guide to get familiar with the features.

User guide

Once an administrator has completed the Administrator guide, you can follow the steps below to get familiar with the app's features.

Step 1: Enable the local check

Local checks allow you to verify your commits on your local machine before they are created. This way, you can catch and fix problems immediately rather than at push or review time.

Steps:

1. Go to the repository in Bitbucket Cloud, click Apps → Commit policy.
2. Click Enable local check and follow the wizard steps.
3. Don't forget to execute the test steps instructed by the wizard.
4. The local check is working! ✅

Step 2: View the merge check

Merge checks make sure pull requests follow the commit policy. You can view the results right on the pull request screen.

Steps:

1. Go to the repository in Bitbucket Cloud.
2. Go to Pull requests, and click any open pull request.
3. Look at the Commit policy section in the right-bar.
4. If the pull request meets all the commit policy requirements, you'll see "Satisfied". Otherwise, it will show "N violations".
5. The merge check definitely works! ✅

Step 3: Resolve violations

To learn how to resolve violations, start by finding a pull request that shows "N violations". We'll use it as our example.

Steps:

1. View the violation list in the Commit policy section in the right-bar.
2. For each violation:
   1. Make the change needed to resolve it:
      1. The pull request title is missing the work item key? → Make sure to add one!
      2. The pull request description is empty? → Write it!
      3. The work item is not assigned to you? → Update the work item (or choose another)!
      4. ... and so on.
   2. Re-run the merge check:
      1. If the violation was related to a commit → Push the fixed commit to the source branch! The merge check will re-run automatically.
      2. If the violation was related to anything else → Click the icon next to the "Commit policy satisfied" check.
         (If the icon isn't available, click the pull request Approve button at the top, then click Unapprove to undo it. This workaround triggers a merge check re-run. It's needed because Bitbucket doesn't always show the icon when expected.)
3. Repeat these steps until the check status shows "Satisfied."
4. Your pull request is perfect! ✅

🎉 Congratulations! You now know how to use commit policies to keep your pull requests clean, consistent, and high quality.

Questions?

Ask us any time.