App Development & Staff Augmentation Company India, USA

Bitbucket Pipelines

Bitbucket Pipelines is Atlassian's built-in CI/CD system for Bitbucket Cloud repositories. Like GitLab CI, everything is configured in a single YAML file at the root of your repository. Pipelines' tight integration with Jira makes it a natural choice for teams already using the Atlassian ecosystem.

The bitbucket-pipelines.yml file

Commit a bitbucket-pipelines.yml file to the root of your repository and Bitbucket will automatically run pipelines on push. No webhooks or external service configuration required.

Minimal bitbucket-pipelines.yml

YAML

image: node:20

pipelines:
  default:
    - step:
        name: Test
        caches:
          - node
        script:
          - npm ci
          - npm test

image key

The top-level `image:` sets the default Docker image. You can override it per step with `image:` inside the step definition.

Full pipeline for a web application

bitbucket-pipelines.yml — complete web app pipeline

YAML

image: node:20-alpine

definitions:
  caches:
    npm: ~/.npm
  steps:
    - step: &install-test-build
        name: Install, Lint & Test
        caches:
          - npm
        script:
          - npm ci
          - npm run lint
          - npm test
          - npm run build
        artifacts:
          - dist/**

pipelines:
  # Runs on every push to any branch without a specific rule
  default:
    - step: *install-test-build

  # Runs on push to specific branches
  branches:
    main:
      - step: *install-test-build
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - pipe: atlassian/aws-s3-deploy:1.4.0
              variables:
                AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
                AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
                AWS_DEFAULT_REGION: us-east-1
                S3_BUCKET: my-production-bucket
                LOCAL_PATH: dist

    develop:
      - step: *install-test-build
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - pipe: atlassian/aws-s3-deploy:1.4.0
              variables:
                AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID
                AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY
                AWS_DEFAULT_REGION: us-east-1
                S3_BUCKET: my-staging-bucket
                LOCAL_PATH: dist

  # Runs when a pull request is created or updated
  pull-requests:
    '**':
      - step:
          name: PR Checks
          caches:
            - npm
          script:
            - npm ci
            - npm run lint
            - npm test

Deployment environments

Bitbucket Pipelines has first-class deployment environments. Setting deployment: production on a step tells Bitbucket to track this as a production deployment, linking it to Jira issues automatically.

deployment: test — for test/QA environments.
deployment: staging — for staging/pre-production environments.
deployment: production — for the live environment.
Each deployment appears in the Deployments dashboard with a history timeline.
Jira issues referenced in commit messages are automatically marked as deployed.

Multiple deployment environments

YAML

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

    - step:
        name: Deploy Staging
        deployment: staging
        script:
          - ./deploy.sh staging

    - step:
        name: Deploy Production
        deployment: production
        trigger: manual     # human must click 'Run' in Bitbucket UI
        script:
          - ./deploy.sh production

Caching dependencies

Built-in and custom caches

YAML

definitions:
  caches:
    # Custom cache for npm's global cache directory
    npm: ~/.npm

pipelines:
  default:
    - step:
        caches:
          - npm          # custom cache
          - node         # built-in: caches node_modules
        script:
          - npm ci

Built-in caches: node, pip, maven, gradle, composer, dotnetcore.
Custom caches can point to any directory path.
Cache keys are based on the cache name and a hash of relevant lockfiles.
Caches expire after 7 days and after they grow beyond 1 GB.

Parallel steps

Run steps in parallel

YAML

pipelines:
  default:
    - step:
        name: Install
        script:
          - npm ci
        artifacts:
          - node_modules/**

    - parallel:
        - step:
            name: Lint
            script:
              - npm run lint

        - step:
            name: Unit Tests
            script:
              - npm run test:unit

        - step:
            name: Type Check
            script:
              - npm run typecheck

    - step:
        name: Build
        script:
          - npm run build

Repository variables (secrets)

Sensitive values are stored as repository variables in Bitbucket.

Navigate to Repository Settings → Pipelines → Repository variables.
Add variables with optional "Secured" flag (masked in logs).
Access them in YAML as $VARIABLE_NAME.
Deployment variables can be scoped to specific environments.

Using repository variables

YAML

- step:
    name: Deploy
    script:
      - echo "Deploying to $DEPLOY_HOST"
      - rsync -avz dist/ "$DEPLOY_USER@$DEPLOY_HOST:/var/www/html/"
    # $DEPLOY_HOST, $DEPLOY_USER are repository variables
    # $DEPLOY_PRIVATE_KEY would be a secured variable

Warning

Always mark passwords, tokens, and SSH keys as "Secured" when creating repository variables. Secured values are masked in build logs and cannot be accessed via the Bitbucket API.

Jira integration

When your Bitbucket workspace is linked to a Jira project, Pipelines automatically detects Jira issue keys in commit messages and branch names, and tracks the deployment status of each issue.

Branch names and commit messages that link to Jira

Bash

# Branch names with Jira issue keys
git checkout -b PROJ-123-add-payment-feature

# Commit messages with Jira issue keys
git commit -m "PROJ-123: Add Stripe payment integration"

# Bitbucket Pipelines automatically:
# 1. Links the build to Jira issue PROJ-123
# 2. Updates the Jira issue with build/deployment status
# 3. Shows "deployed to staging/production" directly in Jira

Bitbucket Pipelines vs GitHub Actions vs GitLab CI

Feature	Bitbucket Pipelines	GitHub Actions	GitLab CI
Config file	bitbucket-pipelines.yml	.github/workflows/*.yml	.gitlab-ci.yml
Free minutes (private)	50 min/month	2,000 min/month	400 min/month
Free minutes (public)	Unlimited	Unlimited	Unlimited
Jira integration	Native and seamless	Via Actions	Via integrations
Self-hosted runners	Yes (Runners for Bitbucket)	Yes	Yes (GitLab Runner)
Parallel steps	Yes	Yes (jobs in a stage)	Yes
Deployment environments	Built-in (test/staging/prod)	Via environments	Built-in
Marketplace/templates	Atlassian Pipes	GitHub Marketplace	CI templates
Container registry	Via AWS/GCP/Docker Hub	ghcr.io (built-in)	Built-in
Best for	Atlassian stack teams	GitHub-first teams	Complete DevOps

Atlassian Pipes

Pipes are Bitbucket's equivalent of GitHub Actions — reusable Docker-based scripts that perform common CI/CD tasks. Atlassian publishes official pipes for AWS, GCP, Azure, Heroku, Slack, and more.

Using official Atlassian pipes

YAML

- step:
    name: Deploy to Heroku
    script:
      - pipe: atlassian/heroku-deploy:2.4.0
        variables:
          HEROKU_API_KEY: $HEROKU_API_KEY
          HEROKU_APP_NAME: my-app-name

- step:
    name: Slack notification
    script:
      - pipe: atlassian/slack-notify:2.1.0
        variables:
          WEBHOOK_URL: $SLACK_WEBHOOK_URL
          MESSAGE: "Deployment complete!"

Pipeline minutes and pricing

Free plan: 50 build minutes per month (very limited for active projects).
Standard plan: 2,500 minutes/month.
Premium plan: unlimited minutes.
Self-hosted Runners for Bitbucket: run your own runners for free unlimited minutes.
Minutes are shared across the entire workspace (all repositories).

Tip

The 50-minute free tier runs out quickly. For any non-trivial project on Bitbucket, either upgrade to Standard or set up a self-hosted runner to avoid interruptions.