bitbucket-workflow

---
name: bitbucket-workflow
description: Bitbucket best practices for pull requests, Pipelines CI/CD, Jira integration, and Atlassian ecosystem workflows
license: Apache-2.0
---

# 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**
   ```markdown
   ## 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

```yaml
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

```yaml
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

```yaml
pipelines:
  pull-requests:
    '**':
      - step:
          name: Build and Test
          script:
            - npm ci
            - npm test
          condition:
            changesets:
              includePaths:
                - "src/**"
                - "package.json"
```

#### Custom Pipes

```yaml
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

```yaml
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

```yaml
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

```yaml
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:

```yaml
# 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

```yaml
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