Git Commit Message Best Practices for Bitbucket Cloud

Git commit messages matter - explain to your team with best practices

Git commit messages are the unsung heroes of software development. They serve as documentation, debugging aids, and collaboration tools that can make or break a project's maintainability.

For teams using Jira Cloud and Bitbucket Cloud, commit messages become even more critical as they bridge the gap between work items and actual code changes, enabling full traceability and compliance.

Learn about a dedicated solution for these platforms, Better Commit Policy that combines Conventional Commits, Jira and Bitbucket integration, and automated policy enforcement to bring order to development workflows.

The 7 essential best practices for Git commit messages

1. Start with the Jira work item key

Always begin your commit message with a valid Jira work item key to ensure full traceability:

SW-424 feat(auth): add OAuth login integration
DEV-1234 fix(ui): resolve modal z-index issue
DOC-567 docs(readme): update installation guide

Why this matters:

• Links code changes directly to business requirements
• Enables automated workflow transitions in Jira
• Standardize audit trails for compliance requirements
• Allows teams to track progress on specific work items

2. Use Conventional Commit types

Follow the conventional commits specification with these standard types:

Type	Purpose	Example
feat	New feature	SW-123 feat(payment): add Stripe integration
fix	Bug fix	BUG-456 fix(auth): prevent session timeout during upload
docs	Documentation	DOC-789 docs(api): add authentication examples
refactor	Code restructuring	TECH-567 refactor(database): optimize query performance
test	Adding tests	QA-890 test(login): add integration test coverage
chore	Maintenance	MAINT-123 chore(deps): update security dependencies

3. Add scope for context

Include the affected component or area in parentheses:

SW-445 feat(dashboard): add real-time analytics widget
BUG-223 fix(payment): resolve PayPal timeout issues
DEV-778 refactor(auth): extract authentication service

4. Use the imperative mood

Write commit messages as commands that complete the sentence "If applied, this commit will..."

Good examples:

SW-234 feat(profile): enable avatar upload functionality
BUG-567 fix(search): correct special character encoding
DOC-890 docs(deployment): update Kubernetes configuration

5. Keep the subject line under 50 characters

This ensures your message displays properly in all Git interfaces, including the Jira work item key.

6. Follow the 50/72 rule

• 50 characters max for the subject line - Forces concise, focused descriptions
• 72 characters max for body lines - Ensures readability across all interfaces
• Blank line between subject and body - Creates clear visual separation

7. Explain what and why, not how

The code shows how something was done. Your commit message should explain what changed and why it was necessary, with the Jira work item providing full context.

Bringing best practices to life in Bitbucket Cloud

While knowing best practices is important, enforcing them consistently across your team is the real challenge. Better Commit Policy Connector for Bitbucket Cloud transforms these guidelines from documentation into automated enforcement, ensuring every commit meets your standards.

Policy-as-code approach

Better Commit Policy Connector for Bitbucket Cloud uses a .commitpolicy.yml file in your repository root to define and enforce commit standards:

Basic Configuration:

commit:
  rejection-message: "Commit must start with a valid Jira key and follow the conventional format."
  message:
    pattern: (?s)(SW|DEV|BUG|DOC)-\d+ (feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{15,}
    work-item:
      jql: 'project in (SW, DEV, BUG, DOC) and statusCategory="In Progress" and assignee="$commit.author"'
      count: "1+"
      non-matching: "reject"

This configuration automatically:

• Validates Jira work item key format and existence
• Enforces conventional commit types
• Ensures work items are assigned to the committer
• Requires work items to be in "In Progress" status
• Maintains minimum description length

Advanced enforcement features

Sprint-Based validation:

commit:
  message:
    work-item:
      jql: 'project = PROJ and sprint in openSprints() and assignee = "$commit.author"'

Team-Specific rules:

# Frontend team configuration
commit:
  message:
    pattern: (?s)(UI|UX)-\d+ (feat|fix|style)(\(.+\))?: .{10,}
    work-item:
      jql: 'project in (UI, UX) and component = "Frontend" and assignee = "$commit.author"'

# Backend team configuration  
commit:
  message:
    pattern: (?s)(API|DB)-\d+ (feat|fix|refactor|test)(\(.+\))?: .{10,}
    work-item:
      jql: 'project in (API, DB) and component = "Backend" and assignee = "$commit.author"'

Emergency override options:

commit:
  message:
    skip-pattern: "\[EMERGENCY\]|\[HOTFIX\]"
  author:
    skip-pattern: "jenkins|automation|incident-response"

Real-time enforcement integration

Better Commit Policy Connector integrates directly with Bitbucket Cloud's interface, providing:

• Immediate feedback when development leads merge pull requests
• Pull request blocking via pull request rules for non-compliant changes (on Bitbucket Premium)
• Clear error messages explaining exactly what needs to be fixed

Automate compliance to development principles

Selecting the right Git commit message best practices is the first step, but automated enforcement in Bitbucket Cloud with Better Commit Policy is what ensures standards are consistently applied across your entire development team.

The combination of conventional commits, Jira integration, and automated policy enforcement transforms chaotic development workflows into organized, traceable processes that support both agile development and enterprise governance requirements.

Start with basic policies and gradually refine them based on your team's needs, until maintaining high-quality commit standards becomes automatic rather than burdensome with Better Commit Policy for Jira Cloud and Better Commit Policy Connector for Bitbucket Cloud

Are you using a platform other than Bitbucket Cloud? Comment below with the platform for which you need commit policies.