Bitbucket Ops CLI

A command-line interface tool for managing Bitbucket repository and deployment variables through configuration templates.

Features

• 📝 Create configuration templates for Bitbucket repositories
• 🔧 Manage repository and deployment variables
• 🔐 Secure handling of secrets through environment variables
• 📦 Auto-generate templates from .env files
• ✅ Validate templates before execution
• 🚀 Simple DevOps workflow integration

Installation

Using npm (Global Installation)

npm install -g @alpharedsolutions/bitbucket-ops

Using npx (No Installation Required)

npx @alpharedsolutions/bitbucket-ops [command]

Using Yarn

yarn global add @alpharedsolutions/bitbucket-ops

Quick Start

After installation, you can use the CLI with bo (short alias) or bitbucket-ops command:

# Show help
bo --help

# Initialize a template from .env file
bo template init --name api-config

# Validate a template
bo template validate --template config.yaml

# Apply configuration (dry run)
bo apply --template config.yaml --dry-run

# Apply configuration
bo apply --template config.yaml

Usage

Initialize Template from Environment File

# Auto-detect .env.sample or .env file
bo template init --name my-config

# Use specific env file
bo template init --name my-config --env-file .env.production

# Non-interactive mode with auto-detection
bo template init --name my-config --auto

Template Management

# List available templates
bo template list

# Show template details
bo template show --template config.yaml

# Validate template
bo template validate --template config.yaml

Apply Configuration

# Preview changes without applying
bo apply --template config.yaml --dry-run

# Apply configuration
bo apply --template config.yaml

List Variables

# List repository variables
bo list variables --template config.yaml

# List deployment variables
bo list deployment-variables --template config.yaml --environment production

Template Format

Templates use YAML format and support environment variable resolution:

version: "1.0.0"
metadata:
  name: "api-service-config"
  description: "Configuration for API service"

repository:
  url: "https://bitbucket.org/company/api-service"
  
variables:
  repository:
    - name: "API_KEY"
      type: "secret"
      value: "${ENV:API_KEY}"
      required: true
    
    - name: "API_ENDPOINT"
      type: "plain"
      value: "https://api.production.com"
      required: true

deployments:
  - name: "production"
    environment_type: "Production"
    variables:
      - name: "DATABASE_URL"
        type: "secret"
        value: "${ENV:PROD_DATABASE_URL}"
        required: true

Authentication

The Bitbucket CLI supports two authentication methods:

API Token (Recommended)

API tokens provide secure access to Bitbucket's REST API:

1. Create an API token (App Password) at: https://bitbucket.org/account/settings/app-passwords/
2. Grant permissions: Repository (Read, Write, Admin), Pipelines (Read, Write, Variables)
3. Set environment variables:

export BITBUCKET_CLOUD_USERNAME="your-username"
export BITBUCKET_CLOUD_API_TOKEN="your-api-token"

OAuth 2.0 (Alternative)

OAuth provides automatic token refresh and more granular permissions:

1. Create an OAuth consumer at: https://bitbucket.org/{workspace}/workspace/settings/oauth-consumers
2. Set the callback URL to: http://localhost:8080/callback
3. Grant required permissions: account, repository (read/write/admin), pipeline (read/write/variable)
4. Set environment variables:

export BITBUCKET_OAUTH_CLIENT_ID="your-oauth-client-id"
export BITBUCKET_OAUTH_CLIENT_SECRET="your-oauth-client-secret"

See OAuth Setup Guide for detailed instructions.

Note: API tokens are the simplest and most reliable authentication method for CLI tools.

Development

Prerequisites

• Node.js >= 18.0.0
• TypeScript

Setup

# Clone the repository
git clone https://bitbucket.org/alpharedsolutions/bitbucket-ops.git
cd bitbucket-ops

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm run dev

Publishing to NPM

# Build the project
npm run build

# Publish to NPM
npm publish --access public

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and feature requests, please visit: https://bitbucket.org/alpharedsolutions/bitbucket-ops/issues

npx claude-flow@alpha swarm "implement tasks according to ./PRD.md" --claude