Set up and monitor deployments

Overview

Bitbucket Cloud enables teams to define deployment environments, configure pipeline steps, and monitor deployments across different stages of their infrastructure.

Setting Up Deployments

Step 1: Define Environments

When Pipelines is enabled, Bitbucket automatically creates three default environments:

Test
Staging
Production

These environment types serve to logically organize deployments.

Configure Environments

Navigate to Repository settings in the left sidebar
Under the Pipelines section, select Deployments
Select any environment to customize it

Each environment can be customized by:

Changing its name
Setting environment-specific deployment variables
Restricting deployment access (Premium feature)

Step 2: Configure Deployment Steps

Add the deployment keyword to steps or stages in your bitbucket-pipelines.yml file, followed by the environment name.

Basic Deployment

pipelines:
  default:
    - step:
        name: Deploy to production
        deployment: production
        script:
          - python deployscript.py prod

Multi-Environment Pipeline

pipelines:
  branches:
    develop:
      - step:
          name: Deploy to Test
          deployment: test
          script:
            - ./deploy.sh test
    staging:
      - step:
          name: Deploy to Staging
          deployment: staging
          script:
            - ./deploy.sh staging
    main:
      - step:
          name: Build
          caches:
            - node
          artifacts:
            - dist/**
          script:
            - npm install
            - npm run build
      - step:
          name: Deploy to Production
          deployment: production
          script:
            - aws s3 sync dist/ s3://production-bucket/

Ordering Requirements

When using multiple deployment environments, maintain this order in your pipeline configuration:

Test environments
Staging environments
Production environments

Steps within each type can be ordered flexibly.

Deployment Variables

Deployment variables override repository and workspace variables, allowing different values per environment.

Setting Deployment Variables

Go to Repository settings → Deployments
Select the environment
Add variables specific to that environment

Using Deployment Variables

pipelines:
  branches:
    main:
      - step:
          deployment: production
          script:
            - echo "API URL: $API_URL"  # Production value
            - echo "DB Host: $DB_HOST"  # Production value
            - ./deploy.sh

Example: Different Credentials per Environment

Test environment variables:

API_URL=https://api-test.example.com
DB_HOST=test-db.example.com

Production environment variables:

API_URL=https://api.example.com
DB_HOST=prod-db.example.com

Monitoring Deployments

Deployment Dashboard

Access deployment information through the Deployments dashboard at: Repository → Deployments

The dashboard provides:

Deployment history: Click the environment name to view previous deployments
Pipeline access: Select the pipeline number to view logs and run details
Deployment summary: Shows environment details, commits, file changes, and linked Jira issues

Deployment Status

Deployments can have these statuses:

Pending: Waiting to start
In progress: Currently deploying
Paused: Waiting for manual approval
Successful: Completed successfully
Failed: Deployment failed
Stopped: Manually stopped

Manual Deployments

Add manual approval before deployment:

pipelines:
  branches:
    main:
      - step:
          name: Build
          artifacts:
            - dist/**
          script:
            - npm run build
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

Promoting Deployments

Manual deployment steps display a Promote button. This launches a preview screen where you can review commits and file changes before triggering deployment.

Only one in-progress deployment is allowed per environment; subsequent deployments are automatically paused.

Jira Integration

Link Jira and Bitbucket to display related issues on deployment summaries.

Reference Issues in Commits

Use the issue key in commit messages:

git commit -m "PT-323 Add created workers to container cluster"

The deployment summary will automatically show linked Jira issues.

Rollback Deployments

Redeploy previous successful deployments without running the entire pipeline.

Requirements

Initial deployment step must have completed successfully
Deployment permissions must permit redeployment (Premium plan)
Artifacts must not be expired (14-day limit)

How to Rollback

Navigate to Deployments dashboard
Select the environment
Find the previous successful deployment
Click Redeploy button

Deployment Patterns

Progressive Deployment

pipelines:
  branches:
    main:
      - step:
          name: Build
          artifacts:
            - dist/**
          script:
            - npm run build
      - step:
          name: Deploy to Test
          deployment: test
          script:
            - ./deploy.sh test
      - step:
          name: Integration Tests
          script:
            - npm run test:integration
      - step:
          name: Deploy to Staging
          deployment: staging
          trigger: manual
          script:
            - ./deploy.sh staging
      - step:
          name: Smoke Tests
          script:
            - npm run test:smoke
      - step:
          name: Deploy to Production
          deployment: production
          trigger: manual
          script:
            - ./deploy.sh production

Feature Branch Deployments

pipelines:
  branches:
    feature/*:
      - step:
          name: Deploy to Test
          deployment: test
          script:
            - ./deploy.sh test $BITBUCKET_BRANCH
  pull-requests:
    '**':
      - step:
          name: Deploy Preview
          deployment: test
          script:
            - ./deploy-preview.sh $BITBUCKET_PR_ID

Blue-Green Deployment

pipelines:
  branches:
    main:
      - step:
          name: Deploy to Blue
          deployment: production
          script:
            - ./deploy.sh blue
            - ./health-check.sh blue
      - step:
          name: Switch Traffic
          trigger: manual
          script:
            - ./switch-traffic.sh blue

Canary Deployment

pipelines:
  branches:
    main:
      - step:
          name: Deploy Canary
          deployment: production
          script:
            - ./deploy-canary.sh 10  # 10% traffic
      - step:
          name: Monitor Canary
          script:
            - ./monitor.sh canary 300  # Monitor for 5 minutes
      - step:
          name: Full Deployment
          trigger: manual
          script:
            - ./deploy-canary.sh 100  # 100% traffic

Deployment Restrictions

Configure which branches can deploy to specific environments (Premium feature).

Setting Restrictions

Go to Repository settings → Deployments
Select environment
Under Deployment restrictions, specify allowed branches
Use patterns like main, release/*, or v*.*.*

Example Configuration

Production environment:

Allowed branches: main, hotfix/*

Staging environment:

Allowed branches: main, develop, feature/*

Deployment Logs

View detailed logs for each deployment:

Navigate to Deployments dashboard
Select the environment
Click on a deployment
View the full pipeline execution log

Deployment Notifications

Configure notifications for deployment events:

Slack Integration

pipelines:
  branches:
    main:
      - step:
          name: Deploy
          deployment: production
          script:
            - ./deploy.sh
            - |
              curl -X POST $SLACK_WEBHOOK_URL \
                -H 'Content-Type: application/json' \
                -d "{\"text\":\"Deployed build $BITBUCKET_BUILD_NUMBER to production\"}"

Email Notifications

Configure in Repository settings → Pipelines → Settings → Email notifications

Best Practices

Use manual triggers for production - Require approval before deploying to production
Implement progressive deployments - Test → Staging → Production
Add smoke tests - Verify deployments after they complete
Use deployment variables - Keep environment-specific config separate
Enable rollback - Ensure artifacts are available for quick rollback
Monitor deployments - Set up alerts for deployment failures
Document deployment process - Keep runbooks for manual steps
Test rollback procedure - Regularly verify rollback works
Use branch restrictions - Limit which branches can deploy to production
Track deployments in Jira - Link commits to issues for better visibility

Troubleshooting

Deployment Paused

Cause: Another deployment is in progress for the same environment

Solution: Wait for the current deployment to complete or stop it

Artifacts Expired

Cause: Trying to redeploy after artifacts have expired (14 days)

Solution: Run a new pipeline to create fresh artifacts

Permission Denied

Cause: User doesn't have deployment permissions

Solution: Repository admin must grant deployment permissions in settings

Wrong Environment Variables

Cause: Variables not set at deployment level

Solution: Configure environment-specific variables in deployment settings

Next Steps

Set up Variables for environment-specific configuration
Use Artifacts to share build outputs
Configure Triggers for manual deployments
Learn about Pipes for cloud deployments

Was this helpful?

It wasn't accurateIt wasn't clearIt wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community