Using Bitbucket Pipelines Manual Steps for Controlled Production Deployments

The Problem with Fully Automated Production Deployments

When you deploy to production with a fully automated pipeline, a single misconfigured variable or failed sanity check can take down your entire service. You need a pause point—a way to require human review before the final deployment step executes. Bitbucket Pipelines provides this through manual steps, which halt execution and wait for explicit approval.

Configuring Manual Steps in bitbucket-pipelines.yml

Manual steps are defined by adding the when: manual condition to a step. Here's a practical example:

image: atlassian/default-image:latest

pipelines:
  branches:
    main:
      - step:
          name: Test Suite
          script:
            - npm test
      - step:
          name: Build and Push
          deployment: production
          trigger: automatic
          when: manual
          script:
            - docker build -t myapp:$BITBUTEQ_COMMIT .

In this configuration, the test suite runs automatically, but the production deployment waits for a human to click an approval button in the Pipelines UI. The step won't start until someone with write access to the repository clicks "Run”.

Controlling Manual Step Timeouts

By default, manual steps expire after 24 hours. If no one approves within that window, the step is marked as timed out and the pipeline stops. You can configure a shorter timeout using the timeout field:

- step:
    name: Production Deploy
    when: manual
    timeout: 1h
    script:
      - ./deploy.sh

This is particularly useful for time-sensitive deployments where you want to ensure the approval happens while context is still fresh. Set timeouts based on your team's response patterns—too short and you risk frustrating developers, too long and urgent fixes get delayed.

Practical Verification Process

To verify manual steps work as expected:

1. Create a test branch in a development repository
2. Add a bitbucket-pipelines.yml with a manual step
3. Push a commit to trigger the pipeline
4. Observe the Pipelines UI—the manual step should show a "Run" button in a waiting state
5. Click the button and confirm subsequent steps execute

If the button doesn't appear or the step runs automatically, check that when: manual is correctly indented under the step definition.

Trade-offs: Blocking vs. Safety

Manual steps introduce a critical trade-off. They prevent accidental deployments but create a dependency on human availability. If your team is spread across time zones or if the person who needs to approve is unavailable, deployments stall. Consider these mitigation strategies:

• Designated approvers: Assign specific team members as backup approvers
• Shorter timeouts: Use 2-4 hour windows for urgent fixes
• Automated rollback paths: Have a manual rollback step ready if an approved deployment fails

Not every deployment needs a manual gate. Use them strategically for production environments where the cost of an accidental release exceeds the cost of a delayed deployment.