v0.2.1-draft AI Drafted
Home / Guides / Bitbucket

Bitbucket Cloud Hardening Guide

DevOps Last updated: 2026-08-08

Code repository security hardening for Bitbucket Cloud — workspace membership and app access, project permissions, forking, branch restrictions and merge checks, signed commits, and Pipelines secrets and deployment controls.

Product Docs API Docs Hardening Guide
View:

Overview

Bitbucket Cloud is Atlassian’s Git-based code hosting and collaboration platform used by millions of developers for source code management, CI/CD pipelines, and team collaboration. As a critical repository for intellectual property and deployment pipelines, Bitbucket security configurations directly impact code integrity and software supply chain security.

This is a product guide within the Atlassian platform. Organization-wide controls — SAML SSO and enforced authentication policies, two-step verification, SCIM provisioning, IP allowlisting, Marketplace app governance, API token policy, data security policies, and the organization audit log — live in the Atlassian Common Controls hub and are referenced here rather than duplicated. Everything below is Bitbucket-specific: what you configure inside a workspace, a project, a repository, or a pipeline.

Intended Audience

  • Security engineers managing development platforms
  • DevOps administrators configuring Bitbucket workspaces
  • GRC professionals assessing code repository security
  • Platform engineers implementing secure SDLC

How to Use This Guide

  • L1 (Crawl): Essential controls for all organizations
  • L2 (Walk): Enhanced controls for security-sensitive environments
  • L3 (Run): Strictest controls for regulated industries

Scope

This guide covers Bitbucket Cloud security configurations including workspace settings, authentication, branch permissions, and pipeline security. Bitbucket Data Center is covered in a separate guide.

Table of Contents

  1. Authentication & Access Control
  2. Workspace Security
  3. Repository & Branch Protection
  4. Pipelines Security
  5. Monitoring & Compliance
  6. Compliance Quick Reference

1. Authentication & Access Control

Organization authentication is configured in the platform hub. SAML SSO, enforced authentication policies, two-step verification, SCIM provisioning, and IP allowlisting are Atlassian organization controls that apply to Bitbucket along with every other Atlassian product — configure them once at admin.atlassian.com following the Atlassian Common Controls guide §1.1 and §1.4. The control below covers what remains genuinely Bitbucket-specific: workspace membership, groups, and invitation policy.

1.1 Manage User Permissions and Access

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 5.4
NIST 800-53 AC-6

Description

Implement least privilege access for workspace members and manage user lifecycle.

Rationale

Why This Matters:

  • Least-privilege groups limit how much code and infrastructure any single compromised account can reach
  • Removing departed and inactive users closes standing access that attackers and insiders exploit
  • Role-based groups make access auditable and prevent permission sprawl as teams grow
  • Shared accounts destroy attribution, so audit logs cannot tie actions to an individual

Attack Prevented: Privilege escalation, insider abuse, orphaned-account access, lateral movement

ClickOps Implementation

Step 1: Review Workspace Members

  1. Navigate to: Workspace Settings → User groups
  2. Review member list and permissions
  3. Remove inactive or departed users
  4. Never share accounts between users

Step 2: Configure User Groups

  1. Create role-based groups:
    • developers - Read/write access
    • reviewers - Read access
    • admins - Administrative access
  2. Assign minimum necessary permissions

Step 3: Configure Invitation Policies

  1. Navigate to: Workspace Settings → Security → Invitations
  2. Configure:
    • Restrict who can send invitations
    • Allow invitations only to specific email domains
    • Require admin approval for new members

This navigation path was not re-verified against current Atlassian documentation in the latest currency pass — confirm the exact menu location in your workspace before scripting or auditing against it.

Step 4: Regular Access Reviews

  1. Quarterly review of all workspace members
  2. Remove users who no longer need access
  3. Audit group memberships

2. Workspace Security

2.1 Configure Project-Level Permissions

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 3.3
NIST 800-53 AC-3

Description

Configure project-level permissions to manage access at scale across multiple repositories.

Rationale

Why This Matters:

  • Project-scoped permissions enforce consistent least-privilege access across every repository in a project
  • Grouping sensitive repositories under restricted projects keeps confidential code away from the broader workspace
  • Centralized project access reduces the chance of a misconfigured individual repo exposing data
  • Managing access at the project tier prevents the permission drift that accumulates when each repo is configured by hand

Attack Prevented: Unauthorized code access, privilege sprawl, data exposure, misconfiguration

ClickOps Implementation

Step 1: Create Project Structure

  1. Navigate to: Workspace → Projects
  2. Create projects by team or function:
    • frontend-apps
    • backend-services
    • infrastructure
    • sensitive-data

Step 2: Configure Project Permissions

  1. Navigate to: Project Settings → User and group access
  2. Add groups with appropriate permissions:
    • Admin: Full project control
    • Write: Can push and merge
    • Read: View only
  3. Permission changes apply to all repos in project

Step 3: Restrict Repository Creation

  1. Configure who can create repositories
  2. Require repositories to be in a project
  3. Set default project for new repositories

2.2 Manage Third-Party App Access

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 12.8
NIST 800-53 AC-20

Description

Control which third-party applications can access workspace data. This is the workspace-scoped layer of app governance — organization-wide Marketplace app approval, the app block list, and OAuth scope review are configured in the Atlassian Common Controls guide §2.1 and §3.3. Configure both: the organization policy decides which apps may be installed at all, and the workspace app access rules decide which of those may reach this workspace’s repositories.

Rationale

Why This Matters:

  • OAuth apps and integrations often hold broad, long-lived access to source code and can become a supply-chain entry point
  • Reviewing and removing unused apps shrinks the attack surface exposed to third-party compromise
  • Requiring admin approval prevents users from silently granting risky apps access to the workspace
  • A compromised or malicious app can exfiltrate code, secrets, and pipeline configuration at scale

Attack Prevented: Supply-chain compromise, OAuth token abuse, data exfiltration, unauthorized access

ClickOps Implementation

Step 1: Review Installed Apps

  1. Navigate to: Workspace Settings → Installed apps
  2. Review all installed applications
  3. Identify apps with broad permissions
  4. Remove unused or unknown apps

Step 2: Configure App Installation Policy

  1. Navigate to: Workspace Settings → Security → App access rules
  2. Configure:
    • Restrict who can install apps
    • Require admin approval for new apps
    • Block specific apps if needed

This navigation path was not re-verified against current Atlassian documentation in the latest currency pass — confirm the exact menu location in your workspace before scripting or auditing against it.

Step 3: Audit OAuth Authorizations

  1. Review user OAuth authorizations
  2. Revoke unnecessary authorizations
  3. Establish app approval process

2.3 Disable Repository Forking for Private Repos

Profile Level: L2 (Walk)

Framework Control
CIS Controls 3.3
NIST 800-53 AC-3

Description

Prevent unauthorized code distribution by disabling forking for private repositories.

Rationale

Why This Matters:

  • Forks of private repos create uncontrolled copies of proprietary code outside protected-branch and access policies
  • Disabling forking keeps intellectual property and any embedded secrets within governed repositories
  • Forked copies are not covered by the original repo’s branch restrictions, scanning, or audit controls
  • Restricting forks to within the workspace limits how easily code can leave the organization’s boundary

Attack Prevented: Source code exfiltration, intellectual property theft, secret leakage, policy bypass

ClickOps Implementation

Step 1: Configure Workspace Forking Policy

  1. Navigate to: Workspace Settings → Settings
  2. Under Forking:
    • Disable Allow forking for private repositories
    • Or restrict forking to within workspace only

Step 2: Configure Repository-Level Override

  1. For specific repos requiring forks:
  2. Navigate to: Repository Settings → Settings
  3. Configure fork settings as needed

3. Repository & Branch Protection

3.1 Configure Branch Permissions

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 16.9
NIST 800-53 CM-3, SI-7

Description

Configure branch restrictions to protect release and default branches from unauthorized or unreviewed changes.

Rationale

Why This Matters:

  • Without a branch restriction, anyone with write access can push straight to the default branch, so a single compromised developer credential puts code into the build with no review step in between
  • Blocking force pushes and deletions preserves history, which is what makes tampering detectable after the fact — an attacker who can rewrite history can hide the commit that introduced a backdoor
  • Merge checks that require passing builds and a minimum number of approvals turn review from a convention into an enforced gate that cannot be skipped under deadline pressure
  • Branch restrictions are the enforcement point that gives the rest of the pipeline its meaning: signed commits, secret scanning, and deployment permissions all assume code arrived through the protected path

Attack Prevented: Direct push of unreviewed code to production branches, history rewriting to conceal malicious commits, branch deletion, review bypass

ClickOps Implementation

Step 1: Configure Branch Permissions

  1. Navigate to: Repository Settings → Branch restrictions
  2. Add branch restriction for main:
    • Branch pattern: main or master
    • Configure restrictions

Step 2: Configure Merge Restrictions

  1. Add merge restriction:
    • Type: Require passing builds
    • Type: Require approvals
    • Minimum approvals: 1 (or 2+ for L2)

Step 3: Configure Push Restrictions

  1. Prevent direct pushes:
    • Only allow specific users/groups to push
    • Prevent deletions
    • Prevent history rewrites (force push)

3.2 Require Pull Request Approvals

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 16.9
NIST 800-53 CM-3

Description

Require pull request reviews before code can be merged to protected branches.

Rationale

Why This Matters:

  • Mandatory peer review catches malicious or accidental changes before they reach protected branches
  • Resetting approvals on new commits prevents an attacker from sneaking changes in after a clean review
  • Default reviewers ensure the right code owners examine sensitive changes every time
  • Required approvals enforce separation of duties so no single account can merge unreviewed code to production

Attack Prevented: Malicious code injection, unauthorized changes, insider tampering, separation-of-duties bypass

ClickOps Implementation

Step 1: Configure Default Reviewers

  1. Navigate to: Repository Settings → Branch restrictions
  2. Configure merge checks:
    • Minimum approvals: 1 (L1) or 2+ (L2)
    • Enable Reset approvals on source branch changes

Step 2: Configure Default Reviewers

  1. Navigate to: Repository Settings → Default reviewers
  2. Add default reviewers for branches
  3. Configure review requirements

Step 3: Configure Merge Strategies

  1. Navigate to: Repository Settings → Merge strategies
  2. Enable/disable merge strategies:
    • Merge commit
    • Squash
    • Fast-forward (requires linear history)

3.3 Enforce Signed Commits

Profile Level: L2 (Walk)

Framework Control
CIS Controls 16.9
NIST 800-53 SI-7

Description

Require GPG- or SSH-signed commits so Bitbucket rejects any push whose commits cannot be cryptographically attributed to a known key.

Prerequisites

  • Bitbucket Premium. Signed commit enforcement is a Premium-only feature; Free and Standard workspaces cannot enable it.
  • Contributors must have a GPG or SSH signing key registered on their Bitbucket account before enforcement is switched on, or their pushes will start failing.

Rationale

Why This Matters:

  • Signed commits cryptographically verify that code originates from a trusted, identified author
  • Verification blocks attackers from spoofing commit author identities to slip in malicious changes
  • Signature requirements defend the integrity of the software supply chain at the commit level
  • Unsigned commits can be forged with any name and email, undermining attribution and trust

Attack Prevented: Commit spoofing, author impersonation, supply-chain tampering, repudiation

ClickOps Implementation

Step 1: Enable Signed Commits on the Repository

  1. Navigate to: Repository Settings → Repository details → Advanced
  2. Enable Signed commits

This is a repository-level setting, not a branch restriction — it is not configured alongside the merge checks in 3.1.

Step 2: Understand What Enforcement Actually Covers

  • Enforcement happens at git push. Pushes containing unsigned commits are rejected outright rather than flagged after the fact.
  • Historical commits are unaffected. Turning this on does not invalidate or re-verify anything already in the repository, so there is no retroactive breakage to plan around.
  • Pull requests created through the Bitbucket web UI are currently exempt from the enforcement. That is a real gap: a contributor who edits and merges in the browser can still land unsigned commits on a repository with signing enforced. Treat the web-UI path as an exception to close by convention or review policy, not one the setting closes for you.

Step 3: Roll Out Signing Keys First

  1. Have contributors register a GPG or SSH signing key on their Bitbucket account — both key types are supported.
  2. Publish setup instructions and confirm key coverage across active contributors before enabling enforcement, since the failure mode is a hard push rejection mid-work.
  3. Document how reviewers verify signature status on incoming changes.

Source: Require signed commits

4. Pipelines Security

4.1 Secure Pipeline Variables

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 3.11
NIST 800-53 SC-12

Description

Securely manage secrets and variables used in Bitbucket Pipelines.

Rationale

Why This Matters:

  • Secured variables mask secrets in build logs, preventing credential exposure to anyone with log or artifact access
  • Scoping secrets to the right repository, workspace, or deployment level limits the blast radius if one is leaked
  • Centrally managed pipeline secrets avoid hardcoding credentials in source, where they persist in Git history
  • Leaked CI/CD credentials grant attackers access to cloud accounts, registries, and production systems

Attack Prevented: Secret leakage, credential theft, hardcoded-secret exposure, pipeline compromise

ClickOps Implementation

Step 1: Configure Repository Variables

  1. Navigate to: Repository Settings → Repository variables
  2. Add variables with Secured option enabled
  3. Secured variables are masked in logs

Step 2: Configure Workspace Variables

  1. Navigate to: Workspace Settings → Workspace variables
  2. Add shared secrets at workspace level
  3. Enable Secured for sensitive values

Step 3: Configure Deployment Variables

  1. Navigate to: Repository Settings → Deployments
  2. Create deployment environments: staging, production
  3. Add environment-specific variables
  4. Configure deployment permissions

4.2 Configure Deployment Permissions

Profile Level: L2 (Walk)

Framework Control
CIS Controls 16.1
NIST 800-53 CM-3

Description

Restrict who can trigger deployments to production environments.

Rationale

Why This Matters:

  • Restricting production deployments to authorized users prevents unauthorized or accidental releases
  • Branch and manual-trigger restrictions ensure only reviewed code reaches production environments
  • Environment-scoped permissions enforce separation between staging and production access
  • Unrestricted deploy access lets a single compromised account push malicious code straight to production

Attack Prevented: Unauthorized deployment, malicious release, production tampering, separation-of-duties bypass

ClickOps Implementation

Step 1: Configure Deployment Environments

  1. Navigate to: Repository Settings → Deployments
  2. Create environments with appropriate restrictions

Step 2: Configure Environment Restrictions

  1. For production environment:
    • Restrict deployment to specific branches
    • Require manual trigger
    • Restrict who can deploy

Step 3: Pipeline Configuration

Code Pack: Config
hth-bitbucket-4.02-deployment-pipeline.yml View source on GitHub ↗ 
pipelines:
  branches:
    main:
      - step:
          name: Build
          script:
            - npm install
            - npm run build
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh

4.3 Scan for Secrets in Commits

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 16.4
NIST 800-53 IA-5

Description

Implement secret scanning to prevent credentials from being committed.

Rationale

Why This Matters:

  • Secret scanning catches API keys, tokens, and passwords before they are committed and exposed
  • Committed secrets persist in Git history even after deletion, so prevention at commit time is critical
  • Automated scanning provides consistent coverage that manual review of every diff cannot match
  • Leaked credentials in repositories are a primary target for attackers harvesting source code

Attack Prevented: Credential leakage, hardcoded-secret exposure, supply-chain compromise, account takeover

Code Implementation

Code Pack: Config
hth-bitbucket-4.03-secret-scan-pipeline.yml View source on GitHub ↗ 
pipelines:
  default:
    - step:
        name: Secret Scan
        script:
          - pip install trufflehog
          - trufflehog --regex --entropy=False .

5. Monitoring & Compliance

5.1 Enable Audit Logging

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 8.2
NIST 800-53 AU-2

Description

Enable and monitor the Bitbucket workspace audit log for repository and workspace events. This is the Bitbucket-specific log; the organization-wide Atlassian audit log and its SIEM streaming are configured in the Atlassian Common Controls guide §5.1. Forward both — the organization log records identity and app events, while the workspace log records the repository, branch-restriction, and permission changes that the organization log does not.

Rationale

Why This Matters:

  • The workspace audit log is the only record of repository-level actions — repository creation and deletion, branch restriction changes, and workspace permission grants — and none of those appear in the organization audit log
  • An attacker who has obtained write access typically relaxes a branch restriction before pushing; that change is visible in the workspace log and nowhere else, which makes it one of the highest-value events to alert on
  • Monitoring permission changes and repository activity surfaces unauthorized access while it is still actionable rather than after the code has already left
  • Without audit trails, incident response cannot reconstruct what an attacker touched, and cannot establish which repositories need to be treated as compromised

Attack Prevented: Undetected intrusion, silent relaxation of branch protections, insider abuse, privilege misuse, delayed incident response

ClickOps Implementation

Step 1: Access the Workspace Audit Log

  1. Navigate to: Workspace Settings → Audit log
  2. Review recent events

Key Bitbucket Events to Monitor:

  • Repository creation and deletion
  • Branch restriction and merge-check changes
  • Workspace and project permission changes
  • User group membership changes
  • App installations and access-rule changes

Step 2: Forward to Your SIEM Alongside the Organization Log

  1. Configure organization audit log streaming per the Atlassian Common Controls guide §5.1 (SIEM webhook forwarding requires Atlassian Guard Premium)
  2. Collect the workspace audit log in addition, and confirm your SIEM retention exceeds Bitbucket’s native retention window
  3. Alert specifically on branch restriction removal and on repository deletion — both are low-frequency, high-signal events

5.2 Regular Security Reviews

Profile Level: L1 (Crawl)

Framework Control
CIS Controls 5.1
NIST 800-53 CA-7

Description

Conduct regular security reviews of workspace configuration and access.

Rationale

Why This Matters:

  • Recurring reviews catch configuration drift and excess access before attackers exploit it
  • Periodic audits of members and apps remove standing access that accumulates silently over time
  • Reviewing for public repositories prevents accidental exposure of proprietary code
  • Without regular reviews, misconfigurations and stale permissions persist as an open attack surface

Attack Prevented: Configuration drift, privilege creep, accidental exposure, stale-access abuse

Review Checklist

Monthly Reviews:

  • Review workspace member list
  • Audit admin access
  • Review installed apps
  • Check for public repositories

Quarterly Reviews:

  • Full access review
  • Branch protection audit
  • Pipeline security review
  • Secret rotation check

6. Compliance Quick Reference

SOC 2 Trust Services Criteria Mapping

Control ID Bitbucket Control Guide Section
CC6.2 Workspace membership least privilege 1.1
CC6.3 Project-level permissions 2.1
CC6.7 Forking restrictions 2.3
CC7.1 Branch protection 3.1
CC8.1 Pull request approvals 3.2
CC7.2 Workspace audit logging 5.1

Organization-level criteria (CC6.1 SSO and 2SV, CC6.6 IP allowlisting) map to the Atlassian Common Controls guide §1.1 and §1.4.

NIST 800-53 Rev 5 Mapping

Control Bitbucket Control Guide Section
AC-6 Workspace membership least privilege 1.1
AC-3 Project-level permissions 2.1
AC-20 Third-party app access 2.2
CM-3 Branch protection 3.1
SI-7 Signed commits 3.3
SC-12 Pipeline secret management 4.1
AU-2 Workspace audit logging 5.1

Organization-level controls (IA-2(1) MFA, IA-8 SSO, AC-17 remote access restriction) map to the Atlassian Common Controls guide §1.1 and §1.4.

Appendix A: Plan Compatibility

Feature Free Standard Premium
Workspace user groups and invitation policy (1.1) ✅ ✅ ✅
Project-level permissions (2.1) ✅ ✅ ✅
Workspace app access rules (2.2) Basic ✅ ✅
Forking restrictions (2.3) ✅ ✅ ✅
Merge checks (3.1, 3.2) Basic ✅ ✅
Signed commit enforcement (3.3) ❌ ❌ ✅
Deployment permissions (4.2) ❌ ✅ ✅
Audit log (workspace) (5.1) ❌ ❌ ✅

Organization-level features — SAML SSO, enforced two-step verification, and IP allowlisting — depend on the Atlassian Guard subscription and product plan rather than the Bitbucket plan alone. See the Atlassian Common Controls guide Appendix A for the Guard capability matrix.

Appendix B: References

Official Atlassian Documentation:

API & Developer Tools:

Compliance Frameworks:

  • SOC 2 Type II and ISO/IEC 27001:2022 apply to Bitbucket Cloud as part of the Atlassian Cloud platform; request the current attestation reports through your Atlassian account team
  • SOX and PCI DSS compliance obligations are met through platform-level controls plus the workspace controls in this guide

Security Incidents:

  • May 2024 — Plaintext Secrets Leak in Pipeline Artifacts: Mandiant discovered that Bitbucket Cloud pipeline artifacts could unintentionally expose plaintext authentication secrets (including AWS credentials) stored in “Secured Variables.” Attackers exploited this to attempt AWS account compromise. (Vorlon Report)
  • 2024 — Bitbucket Data Center Vulnerabilities: 20 high-severity vulnerabilities (CVSS > 7.4) patched across Bitbucket Data Center/Server, including CVE-2024-38819 (CVSS 7.5, path traversal). (Stack.Watch Tracker)
  • 2024 — Infrastructure Reliability: 38 service incidents recorded with over 207 hours of total downtime; approximately half classified as major or critical impact. (GitProtect Report)

Third-Party Resources:

Changelog

Date Version Maturity Changes Author
2026-08-08 0.2.1 draft Currency pass. 3.3: correct signed commits — it is a repository setting at Repository Settings → Repository details → Advanced → Signed commits, not a branch restriction, and it is Premium-only; enforcement rejects unsigned commits at git push, historical commits are unaffected, GPG and SSH signing keys are both supported, and pull requests created through the Bitbucket web UI are currently exempt from enforcement; drop the “(if available)” hedge. Appendix A: add the 3.3 plan row. Appendix B: remove the Atlassian Trust Center and Customer Trust Center rows and reroute the SOC 2 / ISO 27001 lines away from them; add the signed-commits doc. Annotated as unverified this pass: the 1.1 invitation-policy and 2.2 app-access-rules workspace navigation paths (candidate documentation URLs returned 404). Recorded for future passes: Bitbucket Cloud ships no native secret scanning — the security documentation lists only the Snyk integration — so 4.3’s Code Pack approach is correct and should not be “fixed” to point at a native feature. Changelog row order corrected Claude Code (Opus 5)
2026-08-08 0.2.0 draft Restructure as a product guide under the Atlassian platform hub: add platform/platform_slug/product frontmatter and a hub pointer. Remove duplicated organization-level controls — former 1.1 two-step verification and 1.2 SAML SSO now live in Atlassian §1.1, former 1.3 IP allowlisting now lives in Atlassian §1.4. Renumber former 1.4 to 1.1; sections 2-5 unchanged. Scope 5.1 to the Bitbucket workspace audit log with a hub cross-reference, cross-reference org app governance from 2.2, and complete the 3.1 rationale with an Attack Prevented line Claude Code (Opus 5)
2026-06-29 0.1.2 draft Add cheat-sheet Description and Rationale for all controls Claude Code (Opus 4.8)
2026-02-19 0.1.1 draft Extract inline code blocks to Code Pack files (sections 4.2, 4.3) Claude Code (Opus 4.6)
2025-02-05 0.1.0 draft Initial guide with workspace security, branch protection, and pipeline security Claude Code (Opus 4.5)

Contributing

Found an issue or want to improve this guide?