d-subrahmanyam/bitbucket-workflow

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

1. Keep PRs focused and reviewable

   • One feature or fix per PR
   • Include context in the description

2. PR Title Convention

   • Reference Jira issue: PROJ-123: Add user authentication
   • Use conventional format: feat: implement login page

3. 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

1. Add reviewers - Select appropriate team members
2. Use tasks - Create tasks for actionable feedback
3. Approve or request changes - Clear approval workflow
4. 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

1. Use descriptive branch names with Jira keys
2. Configure branch permissions for main branches
3. Implement comprehensive pipelines with proper stages
4. Use pipes for common tasks (AWS, Docker, etc.)
5. Enable smart commits for Jira updates
6. Set up deployment environments with proper permissions
7. Use repository variables for secrets
8. Configure merge checks for quality gates
9. Leverage Atlassian integrations for seamless workflow