Pre-commit hooks on Bitbucket Cloud: catch commit violations before they exist

[#1]

If you've ever had a pull request blocked at merge time because a developer forgot to include a Jira key in their commit message, you know the drill. The developer has to amend the commit, force-push, and the reviewer has to re-check. Everyone's time goes into fixing something that should have been a 2-second correction before the commit was created.

That's the problem pre-commit hooks solve.

 

What are pre-commit hooks?

A pre-commit hook is a commit policy verification that runs on the developer's machine at git commit time, before the commit object is created. The hook performs a local check against your policy. If a commit violates it (wrong message format, missing Jira work item key, unresolved Jira work item), Git rejects it immediately with a clear message.

The changes stay staged, the developer fixes the message, and tries again. Nothing non-compliant ever reaches your repository.

✗ 1 violation found
  Commit message must start with a valid Jira work item key (e.g. PROJ-123)
  Fix the violation and commit again.

The pre-commit hook is installed as a standard Git hook that lives in the repository alongside your code. Every developer who clones or pulls the repository receives it automatically, though manual setup is still required. It works with the CLI, GUI clients like SourceTree or GitKraken, and IDE plugins.

How is this different from merge checks?

Merge checks (which Better Commit Policy Connector has supported on Bitbucket Cloud for a while) run at pull request merge time on the server. They're the hard gate: nothing enters your target branch without passing policy, and they apply to every developer regardless of local setup. If you're new to enforcing commit rules on Cloud at all, there's a good primer on commit policy enforcement in Bitbucket Cloud that covers the merge check side.

Pre-commit hooks run earlier, on the developer's machine, and catch commit-level violations before they ever become anyone else's problem.

They're not alternatives. Merge checks remain the primary enforcement layer. Pre-commit hooks reduce the average cost of a violation from "blocked PR + coordination" to "2-second fix before the commit exists."

What's new

Pre-commit hooks are available on Bitbucket Cloud, making Better Commit Policy Connector the only Bitbucket Cloud app that can enforce commit policy with pre-commit hooks on the developer's machine.

Bitbucket Cloud doesn't support custom server-side hooks, so there's no native way to do this. The app fills that gap.

 

How to enable it

Pre-commit hooks are part of Better Commit Policy Connector for Bitbucket Cloud, which works alongside Better Commit Policy for Jira Cloud (the main app; both need to be installed).

Two steps, both quick:

1. Add the resource files to the repository (once, by any team member with write access). Go to the repository → Apps → Commit policy → Settings → Add next to any missing resource files.
2. Enable the pre-commit hooks on each developer's clone (once per developer). Go to the repository → Apps → Commit policy → Enable pre-commit hooks → follow the wizard.

After that, the pre-commit hook runs automatically on every commit in that clone.

If a developer needs to skip it occasionally (offline, emergency fix), they can add #skipcheck to the commit message for a single commit or temporarily disable it.

A reminder: Better Commit Policy Connector is a companion app to Better Commit Policy for Jira, and both apps are needed for the full solution to work!

Who this is particularly useful for

Any team with code change standards will benefit, but the impact is most obvious for:

• Regulated industries: SOX, IEC 62304, ISO 9001, HIPAA. Clean commits from the start means a cleaner audit trail with no remediation entries.
• Larger engineering teams: at scale, "everyone knows the convention" breaks down. Pre-commit hooks make the policy automatic, not aspirational.
• Teams already using merge checks: pre-commit hooks reduce the friction your developers experience without removing the server-side guarantee.

1. Better Commit Policy Connector for Bitbucket Cloud is free

2. Better Commit Policy for Jira Cloud is free to try for 30 days

3. Reach out to us and our team at Midori is happy to answer questions about setup or how pre-commit hooks and merge checks work together.