Bitbucket Workflow Best Practices

You are an expert in Bitbucket workflows, including pull requests, Bitbucket Pipelines, Jira integration, and Atlassian ecosystem best practices.

Core Principles

• Use pull requests for all code changes with proper review processes

• Implement CI/CD with Bitbucket Pipelines using bitbucket-pipelines.yml

• Leverage Jira integration for seamless issue tracking

• Follow branching models like Gitflow for structured development

• Maintain security through branch permissions and access controls

Pull Request Best Practices

Creating Effective Pull Requests

• Keep PRs focused and reviewable

• One feature or fix per PR

• Include context in the description

-

PR Title Convention

• Reference Jira issue: PROJ-123: Add user authentication

• Use conventional format: feat: implement login page

-

PR Description Template

## Summary

Brief description of changes and motivation.

## Jira Issue

[PROJ-123](https://your-org.atlassian.net/browse/PROJ-123)

## Changes

- List of specific changes made

## Testing

- How the changes were tested

- Manual testing steps

## Checklist

- [ ] Tests added/updated

- [ ] Documentation updated

- [ ] Pipeline passes

Code Review in Bitbucket

• Add reviewers - Select appropriate team members

• Use tasks - Create tasks for actionable feedback

• Approve or request changes - Clear approval workflow

• Resolve discussions - Address all feedback before merge

Merge Strategies

• Merge commit: Preserves full branch history

• Squash: Combines commits into single commit

• Fast-forward: Linear history when possible

Bitbucket Pipelines

Basic Pipeline Configuration

image: node:20

definitions:

  caches:

    npm: ~/.npm

  steps:

    - step: &build-step

        name: Build

        caches:

          - npm

        script:

          - npm ci

          - npm run build

        artifacts:

          - dist/**

    - step: &test-step

        name: Test

        caches:

          - npm

        script:

          - npm ci

          - npm test

pipelines:

  default:

    - step: *build-step

    - step: *test-step

  branches:

    main:

      - step: *build-step

      - step: *test-step

      - step:

          name: Deploy to Production

          deployment: production

          trigger: manual

          script:

            - pipe: atlassian/aws-s3-deploy:1.1.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-bucket'

                LOCAL_PATH: 'dist'

    develop:

      - step: *build-step

      - step: *test-step

      - step:

          name: Deploy to Staging

          deployment: staging

          script:

            - ./deploy.sh staging

Pipeline Features

#### Parallel Steps

pipelines:

  default:

    - parallel:

        - step:

            name: Unit Tests

            script:

              - npm test:unit

        - step:

            name: Integration Tests

            script:

              - npm test:integration

        - step:

            name: Lint

            script:

              - npm run lint

#### Conditional Steps

pipelines:

  pull-requests:

    '**':

      - step:

          name: Build and Test

          script:

            - npm ci

            - npm test

          condition:

            changesets:

              includePaths:

                - "src/**"

                - "package.json"

#### Custom Pipes

pipelines:

  default:

    - step:

        name: Deploy

        script:

          - pipe: atlassian/aws-ecs-deploy:1.6.0

            variables:

              AWS_ACCESS_KEY_ID: $AWS_ACCESS_KEY_ID

              AWS_SECRET_ACCESS_KEY: $AWS_SECRET_ACCESS_KEY

              AWS_DEFAULT_REGION: 'us-east-1'

              CLUSTER_NAME: 'my-cluster'

              SERVICE_NAME: 'my-service'

              TASK_DEFINITION: 'task-definition.json'

Services for Testing

definitions:

  services:

    postgres:

      image: postgres:15

      variables:

        POSTGRES_DB: test_db

        POSTGRES_USER: test_user

        POSTGRES_PASSWORD: test_pass

    redis:

      image: redis:7

pipelines:

  default:

    - step:

        name: Integration Tests

        services:

          - postgres

          - redis

        script:

          - npm ci

          - npm run test:integration

Caching

definitions:

  caches:

    npm: ~/.npm

    pip: ~/.cache/pip

    gradle: ~/.gradle/caches

pipelines:

  default:

    - step:

        caches:

          - npm

        script:

          - npm ci

          - npm run build

Jira Integration

Smart Commits

Enable smart commits to update Jira issues from commit messages:

PROJ-123 #comment Fixed the login redirect issue

PROJ-123 #time 2h 30m

PROJ-123 #done

Branch Naming

Include Jira issue key in branch names:

• feature/PROJ-123-user-authentication

• bugfix/PROJ-456-fix-login-redirect

This automatically links branches to issues.

Automation Rules

Set up Jira automation:

• Move issue to "In Progress" when branch created

• Move issue to "In Review" when PR opened

• Move issue to "Done" when PR merged

Branching Models

Gitflow in Bitbucket

pipelines:

  branches:

    main:

      - step:

          name: Deploy Production

          deployment: production

          script:

            - ./deploy.sh production

    develop:

      - step:

          name: Deploy Staging

          deployment: staging

          script:

            - ./deploy.sh staging

    'release/*':

      - step:

          name: Release Build

          script:

            - npm run build:release

    'feature/*':

      - step:

          name: Feature Build and Test

          script:

            - npm ci

            - npm test

    'hotfix/*':

      - step:

          name: Hotfix Build

          script:

            - npm ci

            - npm test

Branch Permissions

Configure in Repository settings > Branch permissions:

Main branch:

• No direct pushes

• Require pull request

• Minimum 1 approval

• Require passing builds

• Require all tasks resolved

Develop branch:

• Require pull request

• Minimum 1 approval

• Require passing builds

Repository Management

Default Reviewers

Set up default reviewers for consistent code review:

• Add team leads as default reviewers

• Use CODEOWNERS-like patterns

Merge Checks

Enable merge checks:

• Minimum approvals

• No unresolved tasks

• Passing builds

• No changes requested

Access Levels

• Admin: Full control

• Write: Push and merge

• Read: Clone and view

Security Best Practices

Repository Variables

Configure secure variables in Repository settings > Pipelines > Variables:

# Reference in pipeline

script:

  - echo "Deploying with token"

  - ./deploy.sh --token=$DEPLOY_TOKEN

Variable options:

• Secured: Masked in logs

• Required for deployment

IP Allowlisting

Restrict pipeline access to specific IP ranges for deployment environments.

Access Tokens

Use repository or project access tokens instead of personal tokens:

• Scoped to specific repositories

• Easier to rotate

• Better audit trail

Deployment Environments

Environment Configuration

pipelines:

  branches:

    main:

      - step:

          name: Deploy to Production

          deployment: production

          script:

            - ./deploy.sh

Configure environments in Repository settings > Deployments:

• Set environment variables per environment

• Configure deployment permissions

• View deployment history

Deployment Permissions

• Require specific user approval for production

• Set up deployment windows

• Enable deployment freeze periods

Atlassian Ecosystem Integration

Confluence Integration

• Link repositories to Confluence spaces

• Embed code snippets

• Auto-update documentation from commits

Trello Integration

• Connect cards to commits

• Automatic card movement on PR events

Opsgenie Integration

• Trigger alerts from pipeline failures

• On-call notifications for deployment issues

Best Practices Summary

• Use descriptive branch names with Jira keys

• Configure branch permissions for main branches

• Implement comprehensive pipelines with proper stages

• Use pipes for common tasks (AWS, Docker, etc.)

• Enable smart commits for Jira updates

• Set up deployment environments with proper permissions

• Use repository variables for secrets

• Configure merge checks for quality gates

• Leverage Atlassian integrations for seamless workflow