In this page

Overview

This guide provides an overview of configuring commit policies using the Better Commit Policy Connector app.

Commit policy as code

Better Commit Policy Connector implements the modern approach known as "x-as-code" for commit policies. Generally speaking, policy as code means managing every software components, including all kinds of policies, as code. For this app in particular, it means defining commit policies through version-controlled configuration files.

This approach offers several benefits:

  • Flexibility. It supports defining different policies for different repositories or branches.
  • Consistency. Policies are consistently applied across all repositories of the same project, including forks and clones.
  • Collaboration. Developer teams can maintain commit policies using familiar workflows. (For example, they can propose and review policy updates using pull requests.)
  • Integration. The configuration file written in YAML can be easily integrated with other tools, such as automation frameworks and security platforms.
  • Audit trail. Tracking policy changes in Git provides a clear audit trail.

Commit policy resource files

The app's logic for verifying whether the commit policy is satisfied by changes and commits relies on two resource files checked into your repository:

  1. .commitpolicy.yml is a YAML format configuration file. It defines the commit policy and its rules.
  2. commit-msg is a hook script written in Python. It runs the checks locally whenever a developer creates a commit.

For the app to work correctly, both files must be present and their content must be in good shape — correct format and intact integrity.

Manage the resource files

A dedicated popup called Commit policy settings in Bitbucket lets you manage the resource files without touching the repository directly. While you could manage them like any other file, this interface makes it easier, faster, and less error-prone.

To access the Commit policy settings popup:

  1. Go to the repository in Bitbucket, click Apps (left-bar) → Commit policy.
  2. Click the Settings button on the top right.

The resource file management screen gives you a clear overview of each file's status and lets you manage each file with a single click. Because the files live in the repository, developers stay in sync simply by pulling.

Statuses

Each resource file is shown with a status that reflects its current condition. The available actions follow naturally from that status.

Status Description Available actions
Healthy The file exists and its content is correct and up-to-date. View, Reset, Remove
Missing The file does not exist. Add
Corrupt The file exists but has unexpected or invalid content. View, Reset, Remove
Outdated The file exists but a newer version is available. View, Update
Actions

Every action (except View) creates a Git commit on the current branch. Commits follow the Conventional Commits convention, so every change is clear and traceable. Because of creating commits, you need "write" permission on the repository.

This table summarizes the actions for .commitpolicy.yml.

Action Description Commit message
View Opens the file in a new browser tab. No commit is created.
Add Adds .commitpolicy.yml to the repository root. "chore(config): add commit policy configuration file"
Reset Resets .commitpolicy.yml to its default content. "chore(config): reset default commit policy configuration file"
Remove Removes .commitpolicy.yml. "chore(config): remove commit policy configuration file"

This table summarizes the actions for commit-msg.

Action Description Commit message
View Opens the file in a new browser tab. No commit is created.
Add Adds commit-msg to the .commitpolicy-hooks directory. "chore(config): add Git hook script for commit policy checks"
Reset Resets commit-msg to its default content. "chore(config): reset default Git hook script for commit policy checks"
Update Updates commit-msg to the latest version. "chore(config): update Git hook script for commit policy checks"
Remove Removes commit-msg. "chore(config): remove Git hook script for commit policy checks"

Configure the commit policy

Where is the configuration file?

As you understand by now, you configure your commit policy through a YAML format configuration file checked to the code. The commit policy configuration file is located in the root directory of your repository and is named .commitpolicy.yml.

Add the commit policy

If the configuration file does not yet exist in the repository, you need to add it first. To do that, open the Commit policy settings popup and use the Add command next to .commitpolicy.yml. This creates the file with a valid starter configuration and commits it to the repository as the app user.

Edit the commit policy

You can view and edit the configuration file either directly in your local clone or through the Bitbucket web interface.

To configure the commit policy, modify the relevant fields in the YAML file.

Propagate commit policy changes

To contribute changes to the blessed repository (as the "source of truth"):

  1. Edit the .commitpolicy.yml configuration file in your local clone or in the Bitbucket UI.
  2. Commit the changes.
  3. If you edited the file locally, push the changes.
  4. Unless you edited the file in the blessed repository, send a pull request to the blessed repository.

When a policy is updated in the blessed repository, the changes propagate naturally through standard Git operations.

Specifically:

  • Creating a new fork: the fork will receive the latest policy configuration.
  • Creating a new clone: the clone will receive the latest policy configuration.
  • Syncing: the target that pulls (merges) changes from another repository (branch) will receive the updated policy configuration.

It guarantees that all team members operate under the same policy standards automatically. For example, if the rule for commit message length is updated to require a minimum of 20 characters instead of 10, all forks and clones of the repository will automatically receive this new requirement once they pull the latest code changes.

Configure the hook script

The hook script is the client-side component that implements local checks. It is a standard Git commit-msg hook, written in Python for portability across platforms. Git will execute it every time before a developer creates a commit.

Where is the hook script file?

Just like the commit policy configuration file, the hook script is checked into the repository. Its path in the repository is .commitpolicy-hooks/commit-msg. It is automatically synced to every developer's machine through cloning or pulling.

Normally, Git hooks are not checked into the repository. Because this one is, each developer needs to set the core.hooksPath Git configuration option in their local clone. This tells Git to look for hooks in the .commitpolicy-hooks directory. It is a one-time step — just follow the Enable local check wizard.

Add the hook script

If the hook script does not yet exist in the repository, you need to add it first. To do that, open the Commit policy settings popup and use the Add command next to commit-msg. This adds the correct script to the .commitpolicy-hooks directory and commits it to the repository as the app user.

Edit the hook script

The hook script is a managed resource file — it is provided and maintained by the app. We strongly discourage editing it unless you fully understand the implications.

The primary risk is that future app updates may ship an updated version of the hook script, which would silently overwrite any customizations you have made.

If you need to customize the commit-msg logic, you can add a chained commit-msg hook script that will be executed automatically alongside this one.

Propagate hook script changes

Hook script version updates propagate automatically through standard Git operations, exactly the same way as commit policy configuration changes.

Work with the commit policy

After the resource files were added to the repository, you can view and validate them on the Bitbucket UI.

View the commit policy

While the commit policy configuration file is designed to be human-readable, its raw format may not always be the most user-friendly. The Commit policy screen simplifies this by presenting the policy parameters in a structured and visually organized manner.

To view the commit policy, go to the repository in Bitbucket, click Apps (left-bar) → Commit policy.

The top part includes the following controls:

  • Branch selector: You can switch between repository branches to view their specific policies.
  • Show All toggle: You can reveal all policy parameters, including default or undefined values, for a complete configuration overview. (By default, the screen shows only those parameters that have values explicitly set in the configuration file.)
  • Enable local check button: Opens the Enable local check wizard that guides you through configuring local checks in your local repository. This button is enabled only if all resource files are in Healthy status. If not, click the Settings button to fix the problem first.
  • Settings button: Opens the commit policy settings popup where you can manage the resource files. If the app detects problems with the resource files, the button turns yellow — click it to fix them.
  • Get started button: Opens an interactive, easy-to-follow wizard that guides you through the process of activating the commit policy in the repository. It is an in-app implementation of the Get started guide.

Validate the commit policy

After updating the commit policy configuration file, you can use the Commit policy screen to review and validate your changes. It checks for common issues, such as:

  • YAML formatting errors
  • Unrecognized parameters
  • Invalid JQL queries
  • Incorrect regular expressions (regexes)
  • Invalid boolean values

If there are configuration problems, they will be highlighted next to the affected parameter, making it easy to identify and fix the issue.

View the commit policy insights

You can access the Insights panel from the right-hand sidebar on the Source screen. It gives developers an immediate summary of the commit policy used in the repository.

The panel displays the following information:

  • Commit policy name (if configured)
  • Commit description (if configured)
  • The status of the different checks:
    • A green check mark indicates that the check is actively used in this repository.
    • The timestamp of the last time the check was run.

Next steps?

For more help with your configuration, refer to these documentation pages:

  • The configuration reference explains all available fields and their expected values.
  • The recipes page shows common examples, like enforcing a minimum commit message length or requiring work item keys.
  • The YAML tips page helps you avoid syntax errors and write clean, readable configuration files.

Questions?

Ask us any time.