🚀 Bitbucket Deployment Approval Process Setup Guide

This document outlines the setup for deployment approvals in Bitbucket Pipelines using deployment environments with access controls, instead of manual triggers in the pipeline YAML.

📌 Why Use Deployment Environments?

Bitbucket’s deployment feature allows you to:

Control who can deploy to staging or production
Require pull request approval before deployment
Maintain an audit log of deployments
Reduce the risk of unauthorized production pushes

This is far more secure and auditable compared to trigger: manual.

⚙️ Step 1 – Define Environments in `bitbucket-pipelines.yml`

Update your pipeline to use deployment: instead of trigger: manual.

pipelines:
  branches:
    staging:
      - step:
          name: Build and Prepare
          script:
            - echo "Building app..."
            - go build -o app
          artifacts:
            - app
      - step:
          name: Deploy to Staging
          deployment: staging   # Link to "staging" environment
          runs-on:
            - self.hosted
            - linux.shell
            - nsestaging
          script:
            - echo "Deploying to STAGING..."
            - cp app /path/to/application/code
 
  tags:
    v*:
      - step:
          name: Build for Production
          script:
            - go build -o app
          artifacts:
            - app
      - step:
          name: Deploy to Production
          deployment: production   # Link to "production" environment
          runs-on:
            - self.hosted
            - linux.shell
            - nseprod
          script:
            - echo "Deploying to PRODUCTION..."
            - cp app /path/to/application/code

Exmaples :

pipelines:
  branches:
    staging:
      - step:
          name: Deploy to Staging
          runs-on:
            - self.hosted
            - linux.shell
            - nsepreprod
          script:
            - echo " Deploying to STAGING environment"
            - ls -la /var/www/nse/ || echo "Directory not found, skipping..."
            - go version || echo "Go not installed, skipping..."
            - make --version || echo "No Makefile, skipping..."
            - cp -r ./* /var/www/nse/ || echo "Copying files failed, skipping..."
            - make build || { echo "Build failed, exiting..."; exit 1; }
            - echo " Deployed on Staging"

  tags:
    v*:
      - step:
          name: Tag detected – waiting for approval
          script:
            - echo "Tag '$BITBUCKET_TAG' detected. Awaiting manual approval for production deployment."
      - step:
          name: Approval for Production Deployment
          trigger: manual
          script:
            - echo "Approved! Proceeding with production deployment..."
      - step:
          name: Deploy to Production
          runs-on:
            - self.hosted
            - linux.shell
            - nseprod
          script:
            - echo " Deploying to PRODUCTION environment"
            - echo " Backing up current production binary"
            - cp /path/to/application/code/app /path/to/backup/location || { echo "Backup failed, exiting the script"; exit 1; }
            - go version || echo "Go not installed, skipping..."
            - go mod tidy || echo "No go.mod, skipping..."
            - go build -o app || { echo "Build failed, exiting..."; exit 1; }
            - cp app /path/to/application/code || echo "Copying binary failed, skipping..."
            - echo " Deployed on Production"

⚙️ Step 2 – Configure Deployment Environments in Bitbucket

Navigate to Repository Settings → Deployments
Add new environments:
- staging
- production
Each environment will now be available in Pipelines.

🔒 Step 3 – Set Deployment Permissions

For each environment:

Go to Repository Settings → Deployments → [Environment] → Permissions
Define which groups or users can deploy:
- Staging: Allow DevOps + Senior Developers
- Production: Allow only Release Managers or Ops
Optionally, enable:
- ✅ Require pull request approval before deployment
- ✅ Restrict deployments from specific branches (e.g., only main)

📝 Example Approval Flow

A developer merges a feature branch into main.
The pipeline builds the artifact.
For staging, only approved users can run the deploy step.
For production, a tag (v1.0.0) must be created, and only authorized approvers can deploy.

📊 Benefits

Audit trail – Who deployed, what commit, when.
Access control – Only specific users can trigger staging/production releases.
Reduced risk – No accidental deploys by unauthorized users.
Governance – Enforced approval workflows aligned with DevOps best practices.

✅ With this setup, deployments are secure, auditable, and approval-gated by role, not just by repository access.

Readme Bitbucketrunner