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! 🙂

Administrator guide

Don't worry if this guide looks long or complicated - it's really 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 where needed.

Step 1: Connect your Bitbucket workspace to your Jira site

(estimate: 2 min, requires Jira administrator permission)

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 Jira site.
  2. Install the Better Commit Policy for Jira app to the Jira site (if it is not already).
  3. On the Jira interface, go to Apps (in the left-bar) → Better Commit Policy.
  4. Click Connect a VCS workspace now (on the top).
  5. 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.
  6. Click the workspace URL in the table. (Bitbucket opens in a new browser tab, but keep Jira open, as well.)
  7. ✓ VCS connection 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 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 added!
Step 4: Add a 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 the Bitbucket 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:
    1. In the repository, open Source (in another browser tab).
    2. Click the "..." button → Add file.
    3. Enter .commitpolicy.yml as filename.
    4. Copy this to the file content (but don't commit it yet!): 
      commit-policy:
  name: "FOO commit policy"
vcs-connection:
  id: "..."
commit:
  rejection-message: "Commit messages must be a 5+ chars and start with a FOO work item key!"
  message:
	pattern: (?s)FOO-\d+ [A-Z0-9](\S|\S\s*){4,}
	work-item:
	  jql: 'project=FOO and statusCategory="In Progress" and assignee="$commit.author"'
	  count: "1+"
	  non-matching: reject
pull-request:
  rejection-message: "Pull request titles must be 5+ chars and start with a FOO work item key."
  title:
	pattern: (?s)FOO-\d+ [A-Z0-9](\S|\S\s*){4,}
	work-item:
	  jql: 'project=FOO and statusCategory="In Progress" and assignee="$pull-request.author"'
	  count: "1+"
	  non-matching: reject
  description:
	pattern: (?:\S|\S\s*){9,}
    5. Throughout the file, replace "FOO" with the actual Jira project key associated with the code in the repository.
    6. At line 4, replace "..." with the VCS connection ID with the value you just copied to your clipboard. (Be sure to preserve the brackets!)
    7. Commit it.
    8. 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. ✓ Commit policy successfully added!

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

User guide

Once the commit policy is set up using the Administrator Guide, try out the merge checks.

Step 1: 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 your Bitbucket workspace.
  2. Go to any repository where the commit policy was activated.
  3. Go to Pull requests, and click any open pull request.
  4. Look at the Commit policy section in the right-bar.
  5. If the pull request meets all the commit policy requirements, you'll see "Satisfied". Otherwise, it will show "N violations".
  6. ✓ The merge check definitely works!
Step 2: 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.