Bitbucket Deploy Pipeline Environments

A command line tool to manage Bitbucket pipeline deployment variables for different environments across multiple repositories

Installation

$ npm i -g bitbucket-env-manager

Usage

$ bitbucket-env-manager <command_name>

Available commands

init
generate
------
deploy
list
delete

Setup Bitbucket OAuth Consumer

Before initializing, you need to create an OAuth consumer in Bitbucket:

1. Go to Bitbucket → Workspace settings → OAuth consumers
2. Click Add consumer and configure:
   • Name: Any descriptive name (e.g., "Env Manager")
   • Callback URL: https://bitbucket.org (required even though not used)
   • Check: "This is a private consumer"
   • Permissions:
     • Repositories: Read and Write
     • Pipelines: Read and Write
3. Click Save and copy the Key (Client ID) and Secret

Note: If you see the error "No callback uri defined for the OAuth client", ensure you have set a Callback URL and checked "This is a private consumer".

Initialize Credentials

• It should create ~/.bitbucket_env_manager/<workspace>.env file
• During the auth API calls, this should create access tokens in ~/.bitbucket_env_manager/<workspace>_tokens.json file

bitbucket-env-manager init

• Set OAUTH_CLIENT, OAUTH_SECRET and WORKSPACE

Generate

$ bitbucket-env-manager generate

• Creates a new project manager folder with example for bitbucket environments
• In project_envs/example/info.json set the workspace and repository_slug names from bitbucket.
  • workspace
  • repo

Deploy

$ bitbucket-env-manager deploy

• Select multiple .env files to be deployed to bitbucket from project_envs folder.
• As indicated in example folder, the folder should
  • contain environment variables file with name pattern .env.{0|1|2}.{env_name} .
    • {0|1|2} is for the rank of the environment to be created.
      • 0 -> Test, 1 -> Staging, 2 -> Production
    • {env_name} is the environment name to be created.
  • optionally contain a .env.repo file for repository-level variables that will be deployed once per repository
  • contain info.json file, with
    • workspace : workspace name
    • repo : repository_slug name
    • secured : [], an Array with keys from the env files (including .env.repo) that need to be marked as secured in bitbucket.
    • envs_config : { [env_name] : {admin_only:boolean} }, Config object for each {env_name}. admin_only boolean flag allows to specify if the environment needs to be restricted to be deployed by admins only.

Repository Variables

You can now manage repository-level variables using a .env.repo file:

• Place .env.repo alongside your environment .env files

• Variables in this file will be deployed at the repository level

• These variables will be available to all environments

• The secured array in info.json also applies to repository variables

• Repository variables are deployed only once when multiple environments are deployed together

  Example:

  .env.0.Development filename deployment will delete any existing Development environment and variables from the bitbucket repository, and creates a new Development environment under Test Category.

List

$ bitbucket-env-manager list

• Allows to list variables from existing environment from the repository
• Select the info.json file for the desired repository
• Select the env_name from the list to to view the variables from the environment in bitbucket.

Delete

bitbucket-env-manager delete

• Allows to delete a existing environment from the repository
• Select the info.json file for the desired repository
• Select the env_name from the list to remove the environment from bitbucket.