Bitbucket: Repositories, Pipelines & Deployments

Bitbucket is Atlassian's Git hosting platform, built around the same workspace and project model as Jira and Confluence. What sets it apart from a plain Git host is Pipelines — CI/CD defined as code in a single bitbucket-pipelines.yml file, executed in ephemeral Docker containers, with no separate CI server to install or maintain.

This guide covers Bitbucket the way a team actually uses it day to day: creating workspaces and repositories, protecting branches with permissions and merge checks, writing Pipelines configurations that build, test, and deploy, gating merges on green builds and required reviewers, and shipping to a real server over SSH when a pull request lands on main.

Who this is for

• Engineers whose team already lives in Jira/Confluence and hosts code on Bitbucket.
• Anyone setting up CI/CD who wants pipelines-as-code without running Jenkins.
• DevOps engineers standardizing branch permissions and deployment gates across repos.

You should have the following before working through the commands in this guide:

Git hosting plus built-in CI/CD

At its core Bitbucket is a hosted Git server: it stores repositories, enforces access control, and renders pull requests. Pipelines extends that with CI/CD that lives next to the code — a bitbucket-pipelines.yml file at the repo root defines what runs on every push, on pull requests, and on manual triggers. There is no separate CI product to provision, connect, or keep patched; enabling Pipelines on a repository is a toggle in settings.

The workspace / project / repository hierarchy

How it compares to GitHub Actions and GitLab CI

The concepts map closely across all three platforms, which makes moving between them mostly a syntax exercise rather than a mental model change:

A push (or a pull request event) is matched against the trigger rules in bitbucket-pipelines.yml. A matching pipeline spins up a fresh Docker container per step, runs the configured commands, and — if the branch and step qualify — runs a deployment step that pushes the build output to a target environment:

"Installing" Bitbucket CI/CD means creating a repository (inside a workspace) and flipping Pipelines on — there is no server-side agent to install for Cloud.

# Clone a repo you already created in the Bitbucket UI
git clone git@bitbucket.org:my-workspace/my-repo.git
cd my-repo

# Add a minimal pipelines file and push it
cat > bitbucket-pipelines.yml <<'YAML'
image: node:20

pipelines:
  default:
    - step:
        name: Build and test
        caches:
          - node
        script:
          - npm ci
          - npm test
YAML

git add bitbucket-pipelines.yml
git commit -m "ci: add pipelines config"
git push origin main

Branch permissions

Under Repository settings → Branch permissions, restrict who can push directly and who can merge, per branch or branch pattern:

• Prevent direct pushes to main — require changes to land via pull request.
• Require a minimum number of approvals before a PR can merge.
• Require that the build status is successful before merging is allowed.
• Restrict merge access on release branches (e.g. release/*) to a specific group.

Repository variables and secured variables

Under Repository settings → Repository variables, define values referenced in bitbucket-pipelines.yml as $VARIABLE_NAME. Marking a variable Secured encrypts it at rest and masks its value in build logs:

- step:
      name: Deploy
      script:
        - echo "Deploying with key length ${#DEPLOY_SSH_KEY}"
        - ssh -i <(echo "$DEPLOY_SSH_KEY") deploy@$STAGING_HOST "deploy.sh"

SSH keys for deployment

Under Repository settings → Pipelines → SSH keys, Bitbucket generates (or lets you upload) a dedicated key pair for that repository. Add the public key as an authorized key on the deployment target; Pipelines injects the private key automatically at ~/.ssh/id_rsa inside build containers, and also adds the host to known_hosts via the configured fingerprint:

# Paste the Pipelines-generated public key into the deploy user's authorized_keys
sudo -u deploy mkdir -p /home/deploy/.ssh
echo "ssh-rsa AAAA... bitbucket-pipelines" | sudo -u deploy tee -a /home/deploy/.ssh/authorized_keys
sudo -u deploy chmod 700 /home/deploy/.ssh
sudo -u deploy chmod 600 /home/deploy/.ssh/authorized_keys

Git commands in a Bitbucket workflow

# Clone via SSH (recommended over HTTPS for daily work)
git clone git@bitbucket.org:my-workspace/my-repo.git

# Create a feature branch and push it, opening a PR from the CLI push output link
git checkout -b feature/payment-retry
git push -u origin feature/payment-retry

# Keep a feature branch current with main before requesting review
git fetch origin
git rebase origin/main

# Tag a release (often consumed by a pipelines "tags" trigger)
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0

# Add or update the SSH remote if you cloned over HTTPS originally
git remote set-url origin git@bitbucket.org:my-workspace/my-repo.git

Pipelines YAML syntax basics

Every bitbucket-pipelines.yml is built from the same handful of keys:

image: node:20

pipelines:
  default:
    - step:
        name: Build and test
        script:
          - npm ci
          - npm test

  branches:
    main:
      - step:
          name: Build
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**

  pull-requests:
    '**':
      - step:
          name: Lint and test
          script:
            - npm ci
            - npm run lint
            - npm test

A complete pipeline for a Node.js service: build and test on every branch, then deploy to a Staging environment when main is updated.

image: node:20

definitions:
  caches:
    npm-cache: node_modules

  steps:
    - step: &build-and-test
        name: Build and test
        caches:
          - node
        script:
          - npm ci
          - npm run lint
          - npm test
          - npm run build
        artifacts:
          - dist/**

pipelines:
  default:
    - step: *build-and-test

  pull-requests:
    '**':
      - step: *build-and-test

  branches:
    main:
      - step: *build-and-test
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - pipe: atlassian/ssh-run:0.8.1
              variables:
                SSH_USER: $STAGING_SSH_USER
                SERVER: $STAGING_HOST
                COMMAND: 'cd /srv/app && ./scripts/deploy.sh'
            - pipe: atlassian/rsync-deploy:0.6.1
              variables:
                USER: $STAGING_SSH_USER
                SERVER: $STAGING_HOST
                REMOTE_PATH: '/srv/app/dist'
                LOCAL_PATH: 'dist'

Scenario: a pull request must pass build and test before it can merge, and merging into main should automatically deploy to a staging server over SSH — no manual deploy step, no separate release ticket.

image: node:20

pipelines:
  pull-requests:
    '**':
      - step:
          name: Build and test PR
          caches:
            - node
          script:
            - npm ci
            - npm test

  branches:
    main:
      - step:
          name: Build
          caches:
            - node
          script:
            - npm ci
            - npm run build
          artifacts:
            - dist/**
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - apt-get update && apt-get install -y rsync openssh-client
            - rsync -az --delete dist/ $STAGING_SSH_USER@$STAGING_HOST:/srv/app/dist
            - ssh $STAGING_SSH_USER@$STAGING_HOST "sudo systemctl restart app"

• Reuse step definitions with YAML anchors (&name / *name) so PR checks and production builds run identical steps.
• Always declare artifacts explicitly — never assume a later step can see a previous step's filesystem.
• Use caches for dependency directories (node, docker, pip) to cut build minutes meaningfully.
• Name deployment steps with deployment: <environment> so every release shows up in the Deployments dashboard with a real audit trail.
• Keep the pull-request pipeline fast (lint + unit tests) and push slower integration/E2E suites to the branch pipeline or a scheduled pipeline.
• Pin Docker image tags (e.g. node:20.11) rather than floating tags like latest, so a base image update can't silently break builds.

• Secured variables — store every credential (API tokens, deploy passwords, SSH passphrases) as a Secured repository or deployment variable, never in plain YAML or committed files.
• Branch permissions + required approvals — block direct pushes to main/release branches and require at least one reviewer approval plus a passing build before merge.
• Deployment environment restrictions — scope which branches can deploy to Production, and require manual triggering (deployment gate) for production deploys rather than fully automatic.
• SSH key rotation — rotate the Pipelines-managed SSH key periodically under Repository settings → Pipelines → SSH keys, and revoke it immediately from every target server if a repository's access changes.
• Least-privilege deploy users — the SSH user Pipelines deploys as should only have permissions on the application directory and restart command it needs, not broad sudo.

Bitbucket pairs familiar Git hosting with Pipelines-as-code, so CI/CD configuration travels with the repository instead of living in a separate system. The pieces that make it production-grade are the same ones covered here: branch permissions and required approvals gating what reaches main, secured variables and rotated SSH keys keeping deployment credentials safe, and a bitbucket-pipelines.yml that reuses build/test steps across pull requests and branches so what gets tested is exactly what gets shipped. Practice this end to end on a throwaway repository — open a PR, watch the build gate the merge, then watch the merge itself trigger a real deploy.

• Bitbucket Cloud documentation — support.atlassian.com
• Bitbucket Pipelines configuration reference — bitbucket.org
• Atlassian Pipes marketplace (SSH, rsync, cloud deploy pipes) — bitbucket.org
• Atlassian Community forums — community.atlassian.com
• Atlassian status page — status.atlassian.com