Learn how to configure Bitbucket with Dotenv Vault in a simple Node.js web app. This tutorial assumes you are already familiar with
.env files and know how to sync them.
You can find a complete example repo here.
Make sure you have
Pipelines enabled in your Bitbucket project (requires 2FA). Create a
bitbucket-pipelines.yml file in your project’s
root folder to set your Bitbucket pipeline settings. Add the image details and what steps should be triggered, such as install and build in our case.
# bitbucket-pipelines.yml image: node:10.15.0 pipelines: default: - step: script: - npm install - npm run build
Start by installing the
dotenv-vault-core package with
npm install dotenv-vault-core --save
Reference the Vault module as early as possible in your
index.js code to avoid potential conflicts.
// index.js require('dotenv-vault-core').config() console.log(process.env) // for debugging purposes. remove when ready.
With that out of the way, login and sync with your Vault locally with
npx dotenv-vault pull ci, then proceed with building it via
npx dotenv-vault build.
npx dotenv-vault build
When the building is complete, you will be granted access to the Vault decryption keys, which you can use to access protected environment variables freely. To fetch a key, run
npx dotenv-vault keys ci, where
ci represents the environment you wish to use with Vault, like
The prompt will return a long URL starting with
dotenv://:key and ending in
?environment= followed by the environment you have selected.
npx dotenv-vault keys ci remote: Listing .env.vault decryption keys... done dotenv://:firstname.lastname@example.org/vault/.env.vault?environment=ci
Keep the key you obtained in the previous step safe for now and navigate to your Bitbucket project in the mean time. Once you are there move to Repository settings, then Repository variables at the bottom. In the Repository variables panel, add
DOTENV_KEY in the key field and the decryption key you stored earlier as its value.
Commit those changes safely to code and deploy to Bitbucket.
When the build runs, it will recognize the
DOTENV_KEY, decrypt the .env.vault file, and load the
ci environment variables to
ENV. If a
DOTENV_KEY is not set when developing on local machine, for example, it will fall back to standard Dotenv functionality.
You’ll know things worked correctly when you see
'Loading .env from encrypted .env.vault' in your Bitbucket logs.