Conventional Commits can bring order, clarity, and compliance to your Bitbucket Cloud workspace — but only if your team sticks to the rules.
In this guide for engineering managers, we explore how to write better commit messages, prevent human error, and enforce standards automatically with commit policies in Bitbucket Cloud.
Conventional Commit best practices:
Before diving into the specifics of implementing Conventional Commits in Bitbucket Cloud, let's see some best practices that make these conventions effective.
These tips are about building habits that foster clarity, accountability, and collaboration across your team. Internalizing these principles is key and that's where commit policy tools can help.
- Link to Jira work items: Reference work item keys (e.g.,
SW-424) to maintain traceability. - Use imperative mood: Phrases like "add feature" or "fix bug" are preferred over "added feature" or "fixed bug".
- Separate the subject line from the body with a blank line: This improves readability and ensures tools can correctly parse the commit message.
- Follow branch naming rules: Consistent branch naming (e.g.,
feature/SW-134-add-login-form) complements commit message conventions, making it easier to trace changes and maintain a clean repository structure. - Keep explanations concise: If your commit message links to a Jira work item, you don't need to explain the motivation in detail. The work item contains the full context and reasoning behind the change. Use the commit message to summarize what was changed, not why. It keeps your history clean and easy to scan.
Why commit message conventions matter in Bitbucket Cloud
Commit messages are more than annotations; they’re a source of truth and compliance evidence. Adopting a format like Conventional Commits in Bitbucket Cloud helps every team member communicate change intent consistently — which is especially important for high-velocity or regulated development environments.
Benefits of Conventional Commits:
- Improved traceability: Link code changes directly to Jira work items, enabling faster audits and post-incident reviews.
- Developer accountability: Clear formatting reinforces ownership and helps teams catch context-lacking changes early and recall motivations behind changes after years.
- Automated tooling compatibility: Commit conventions power changelog generation, smart commits, and semantic versioning.
- Audit & compliance: A standardized structure ensures that every change is traceable to a work item, assignee, and requirement — crucial for regulated industries.
However, Bitbucket Cloud doesn't natively enforce commit message standards. This gap can lead to inconsistent messages, making it harder to maintain compliance and traceability.
How to write Conventional Commit messages
Crafting commit messages that follow an agreed-upon convention is both an art and a science. Here's a structured approach to ensure clarity and consistency:
- Start with a change type: Use prefixes like
feat,fix,docs,style,refactor,test, orchoreto categorize the nature of the change. - Optional scope: Specify the section of the codebase affected, enclosed in parentheses, e.g.,
feat(login):. This helps clarify the context of the change, reducing the need for lengthy explanations. - Include work item keys: Incorporate a unique identifier such as a Jira work item key (e.g.,
SW-1234) to associate the commit with a requirement, task, or ticket. This makes tracking, traceability, and compliance verification significantly easier. - Subject line: Write a concise description of the change in the imperative mood, limited to 50 characters.
- Body (optional): Provide a detailed explanation of the change, its rationale, and any relevant context. Wrap lines at 72 characters. Conventional commit messages follow the Git 50/72 rule.
Examples of good Conventional Commit messages
Understanding the theory is one thing; seeing it in practice helps you and your team adopt best practices and use in the production development workflow. Here are some examples of well-structured commit messages:
Commit message after code review:
A commit message after code review documents changes made in response to feedback. A good post-review commit message should summarize the adjustments, and reference requirements those are tied to.
This helps reviewers and future maintainers quickly understand if the required changes were made, streamlining audits and knowledge sharing.
SW-578 fix(ui): Address header alignment feedback Adjusted CSS in the header component to resolve the alignment issue identified during code review. Incorporated reviewer suggestions for improved cross-browser consistency.
Feature addition:
feat(profile): Enable avatar uploads Users can now upload avatars to personalize their profiles. Implements: SW-901
Documentation update:
docs(readme): DOC-566 Update installation instructions Clarified steps for setting up the project locally.
These examples demonstrate clarity, linkage to relevant tasks, and adherence to the Conventional Commits format. Notice that some messages contain Jira work item links at the very beginning of the message, some have it elsewhere. Both can be enforced in the commit policy.
Enforcing commit message conventions automatically
While educating the team on best practices is essential, real consistency requires automated enforcement. Better Commit Policy for Jira Cloud, together with Better Commit Policy Connector for Bitbucket Cloud, offers a unique enterprise-ready solution for enforcing commit message standards in Bitbucket Cloud.
With policy-as-code, you define commit rules in a ".commitpolicy.yml" file placed in the root of your repository. This file describes exactly what makes a commit acceptable—such as message length, required format, or Jira work item links. The app automatically evaluates every commit and pull request against these rules.
When a developer pushes a change and opens a pull request, the policy check runs instantly. If the commit message fails to match your required format—such as not starting with feat, fix, or another allowed type, or missing a valid Jira work item key—the change is rejected. You can also require that referenced Jira work items are in a particular status (like "In Progress") or assigned to the committing user.
Better Commit Policy integrates directly with Bitbucket's merge checks, so non-compliant changes are flagged, or on Bitbucket Premium they are actually cannot be merged.
And because every violation is shown in Bitbucket, developers get fast feedback and can fix problems before they affect the main branch. It's the foundation for teams that want to align developer workflows with structured change management.
Sample commit policy configuration:
This is an example of how you define your conventions in Bitbucket Cloud, in a "policy-as-code" fashion.
This policy ensures clear commit message and pull request formatting and mandatory links to Jira work items. It sets rules for the branch where code changes originate and defines a certain author whose commits are ignored by the policy.
commit:
rejection-message: "Write a 10+ char long commit message, starting with a valid SDAI work item key! Watch for the correct cases."
message:
pattern: (?s)SDAI-\d+ [A-Z0-9](\S|\S\s*){20,}
work-item:
jql: 'project=SDAI and statusCategory="In Progress" and assignee="$commit.author"'
author:
skip-pattern: "john"
pull-request:
rejection-message: "Write a 10+ char long pull request title, starting with a valid SDAI work item key! Also, write a 10+ char long pull request description!"
title:
pattern: (?s)SDAI-\d+ [A-Z0-9](\S|\S\s*){10,}
work-item:
jql: 'project=SDAI and statusCategory="In Progress" and assignee="$pull-request.author"'
description:
pattern: (?:\S|\S\s*){9,}
source-branch:
pattern: (?s)feature/SDAI-\d+ [A-Z0-9]{4,}
Start using commit policies in Bitbucket Cloud
Better Commit Policy apps are used by companies that take traceability seriously. They are trusted in aerospace, medical devices, fintech, automotive, and enterprise SaaS—industries with regulated product requirements or engineering teams with significant responsibility.
✅ Better Commit Policy for Jira Cloud - The central app managing the connections between Version Control Systems and your Jira Cloud.
✅ Better Commit Policy Connector for Bitbucket Cloud - The Bitbucket app where you manage your policy as code. It implements the native merge check that enforces commit and PR rules.
Start a free trial and take control of your Bitbucket commits!