GitHub Actions with Node.js

Learn how to configure GitHub Actions 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.

Initial setup

Create a main.yml file in a .github/workflows/ folder to set your GitHub Actions settings. Add a name for the Action, what should trigger it, and details about the jobs it will perform, such as build and deploy. Specify its behavior for these jobs by picking a target operating system and steps it should take, like installing and running packages.

Most important of all, however, do set an env parameter to store your DOTENV_KEY which you will use to decrypt your Vault and the environment variables it keeps.

Yaml

// .github/workflows/main.yml
name: npm run build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/[email protected]
    - uses: actions/[email protected]
      with:
        node-version: 16
    - run: npm install
    - run: npm run build
      env:
        DOTENV_KEY: ${{ secrets.DOTENV_KEY }}

Example.

Package installation

Start by installing the dotenv-vault-core package with npm.

CLI

npm install dotenv-vault-core --save

Reference the Vault module as early as possible in your index.js code to avoid potential conflicts.

Node.js

// index.js
require('dotenv-vault-core').config()
console.log(process.env) // for debugging purposes. remove when ready.

Example.

Build the Vault

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.

CLI

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 development and production.

The prompt will return a long URI starting with dotenv://:key and ending in ?environment= followed by the environment you have selected.

CLI

npx dotenv-vault keys ci
remote:   Listing .env.vault decryption keys... done

dotenv://:[email protected]/vault/.env.vault?environment=ci

Set deployment

Keep the key you obtained in the previous step safe for now and navigate to your GitHub project in the mean time. Once you are there move to Settings, then Secrets, until you reach Actions, where you can submit a “New Repository Secret.” In the repo secrets panel, add DOTENV_KEY in the key field and the decryption key you stored earlier as its value.

Commit and push

That’s it!

Commit those changes safely to code and deploy to GitHub.

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 GitHub Actions logs.