Bitbucket Setup Checklist for Engineering Teams (2026)

Create Projects in your Workspace (e.g., Backend Services, Frontend, Infrastructure, Mobile). This groups related repos, enables project-level branch restrictions that cascade down, and makes it easier to manage permissions at scale.

Workspace Settings → Groups → Create group. Create groups like developers, senior-engineers, devops, qa before adding people. Assign groups to projects and repos instead of individuals — when someone leaves, remove them from the group and access is revoked everywhere.

Workspace Settings → Security → Two-step verification → Require 2FA for all users. Members without 2FA will lose access until they set it up. Do this before inviting the full team.

Use permission levels: Read (view only), Write (push code, create PRs), Create repositories (can add new repos), Admin (full project control). Most developers should have Write on their project. Only leads need Admin.

Configure branch restrictions and merge checks at the Project level (Project Settings → Branch restrictions / Merge checks) rather than per-repo. New repositories added to the project automatically inherit these rules, so your policies apply consistently without manual setup.

Repository Settings → Branch permissions → Add a rule for main. Set Write access: specific group (your Admin or Senior Lead group only). This forces all engineers to submit pull requests — nobody can bypass review by pushing directly.

On the same branch restriction for main, set Merge access to your developers group. All developers can merge PRs (after checks pass) but nobody can push directly. This is the correct default.

Add branch restrictions with patterns release/* and hotfix/* so all branches matching those patterns are automatically protected. Developers should only be allowed to push to feature/* branches and the restriction rules enforce that.

Set branch restrictions at the Project level so they apply to all existing and future repositories in that project. Per-repo restrictions are useful only when a specific repo needs different rules from the project default.

If a user is in a group with ALLOW and also in a group with DENY, DENY wins. Design your groups carefully — don't add someone to a DENY group unless intentionally blocking that specific person.

Repository Settings → Merge checks → Minimum number of approvals → set to 1 (standard teams) or 2 (critical repos). The PR author's approval is automatically excluded. This is the single most important merge check.

Merge checks → Minimum successful builds → set to 1. This blocks merging if the latest commit on the PR has not passed your Pipelines CI build. Prevents broken code from reaching main.

Merge checks → No changes requested. If any reviewer has clicked 'Request changes', the PR cannot merge until those change requests are resolved. Prevents approved-but-still-flagged code from slipping through.

Merge checks → No incomplete tasks. Reviewers can create checklist tasks on PRs (e.g., 'Update the changelog', 'Add a test for this edge case'). This check blocks merge until all tasks are ticked off.

Merge checks → Minimum approvals from default reviewers. If you've configured default reviewers (specific leads or seniors), this ensures at least one of them approves every PR — not just any random team member.

Premium only: Merge checks → Reset approvals when source branch is updated. Re-reviews are required after any new commits. Without this, an engineer can get approval and then push additional unreviewed changes before merging.

Project Settings → Default reviewers. Add your tech leads or senior engineers. They are auto-added to every PR opened in any repo within the project. You can set 'At least 1 default reviewer must approve' as a merge check.

Unlike GitHub (CODEOWNERS with teams) and GitLab (group approvers), Bitbucket Cloud default reviewers only support individual users — not groups. For group-based auto-assignment, use the CODEOWNERS file instead.

Bitbucket Cloud supports CODEOWNERS at .bitbucket/CODEOWNERS. Unlike default reviewers, CODEOWNERS in Bitbucket does support workspace groups as owners. Use this for teams: /backend/ @your-workspace/backend-team. This is the correct way to do group-based code ownership in Bitbucket.

The file must be named exactly bitbucket-pipelines.yml (lowercase) and placed at the root of the repo. Pipelines will not run without this file. Start with a default pipeline that runs on every push.

Add a pull-requests section with a ** pattern to run your lint and test jobs on every PR regardless of branch name. This is what feeds the 'Minimum successful builds' merge check — without it, the check has nothing to evaluate.

Under your branches: main: pipeline, add trigger: manual to any step that deploys to production. Staging can auto-deploy; production should require a human to click Run. Prevents accidental production deployments.

Add deployment: test, deployment: staging, or deployment: production to your pipeline steps. This creates an Environments page showing deployment history and lets you set environment-specific variables (different database URLs, API keys per environment).

Workspace Settings → Pipelines → Workspace variables (shared across all repos) or Repository Settings → Pipelines → Variables for repo-specific secrets. Toggle the Secured option to encrypt them. Never hardcode credentials in the YAML file.

Use the caches: section to cache your dependency directory. Bitbucket auto-provides a node cache definition. Cache by lockfile hash so it rebuilds only when dependencies change. Reduces average pipeline time by 40-60%.

Bitbucket Pipes are pre-built pipeline steps for AWS S3, Heroku, Terraform, Docker Hub, Slack notifications etc. Use pipes: bitbucketpipelines/aws-s3-deploy instead of writing raw CLI commands. Reduces YAML complexity and maintenance.

Create a separate bot/service Bitbucket account with only the permissions needed for CI tasks (e.g., Read access to repos for cloning, Write for pushing tags). Do not use a personal account — personal account tokens break when that person leaves.

Bitbucket does not include native SAST or dependency scanning. Add security scanning via Pipes (e.g., Snyk: pipe: snyk/snyk-scan:0.7.0, or OWASP Dependency Check). Run in a security stage before the deploy stage.

Review which groups and individuals have Write/Admin access to each repository. Remove access for team members who have changed roles or left. Bitbucket does not automatically revoke access.

Atlassian Access (paid separately) enables SAML SSO and SCIM user provisioning from Okta, Azure AD, etc. When an employee is deprovisioned in your IdP, their Atlassian/Bitbucket access is automatically revoked. Essential for teams larger than 20.

Go to app.gitmore.io → Add Integration → Authenticate with Bitbucket. Connect all active repositories. Gitmore uses Bitbucket webhooks for commit and PR events and never accesses your source code.

Gitmore delivers a morning summary of yesterday's commits, opened and merged PRs, pending reviews, and blocked items. For Bitbucket teams, this replaces the 'any updates?' messages that accumulate in Slack because Bitbucket has no native activity feed.

Gitmore connects Bitbucket activity with Jira tickets in your reports — showing which issues were worked on, which PRs closed tickets, and what's still open. Ideal for Atlassian-stack teams who want their git activity in the context of their sprint.

Unlike GitHub Insights or GitLab's Contribution Analytics, Bitbucket has almost no built-in metrics. Gitmore gives you PR cycle time, commit frequency, team velocity, and deployment frequency — the data that Bitbucket doesn't surface natively.