The project is in a healthy, maintained state
Credentials like passwords, access tokens and other secrets are often passed to sites each by it's own ENV variable. This is both uncool, non-atomic and therefore unreliable. Use this plugin to store your credentials in encrypted YAML files which you can safely commit to your source code repository. In order to use all of them in Bridgetown, you have to set or pass exactly one ENV variable holding the key to decrypt.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Development

Runtime

>= 1.2.0, < 2.0
~> 0, >= 0.2.1
 Project Readme

Version Tests Code Climate GitHub Sponsors

Credentials for Bridgetown

This plugin adds Rails-like encrypted credentials to Bridgetown.

Credentials like passwords, access tokens and other secrets are often passed to sites each by its own ENV variable. This is both uncool, non-atomic and therefore unreliable. Use this plugin to store your credentials in encrypted YAML files which you can safely commit to your source code repository. In order to use all of them in Bridgetown, you have to set or pass exactly one ENV variable holding the key to decrypt.

Thank you for supporting free and open-source software by sponsoring on GitHub or on Donorbox. Any gesture is appreciated, from a single Euro for a ☕️ cup of coffee to 🍹 early retirement.

Installation

First add this gem to your bundle:

$ bundle add bridgetown_credentials

Then enable it in config/initializers.rb:

init :bridgetown_credentials

For the time being, it's necessary to require this gem early in the boot process for the commands to be picked up. Add config/boot.rb to your site reading:

Bundler.setup(:default, Bridgetown.env)
require "bridgetown_credentials"

Secure Installation

This gem is cryptographically signed in order to assure it hasn't been tampered with.

To install it securely, add the author's public key as a trusted certificate and then install the bundle with the trust policy of your choice:

gem cert --add <(curl -Ls https://raw.github.com/svoop/bridgetown_credentials/main/certs/svoop.pem)
bundle install --trust-policy MediumSecurity

Update from 0.x.x to 1.x.x

From version 1.0.0 upwards, this gem uses Dry::Credentials instead of ActiveSupport (which is planned to be ditched from Bridgetown at some point in the future). This requires you to take some additional steps:

  1. Backup the decrypted credentials for every environment:
    bin/bridgetown credentials edit -e ENVIRONMENT
  2. Delete (or move elsewhere) your old encrypted credentials files:
    rm config/credentials/*
  3. Update this gem to a version >= 1:
    bundle update bridgetown_credentials
  4. Create new encrypted credentials files for every environment:
    bin/bridgetown credentials edit -e ENVIRONMENT
  5. Step 4 prints the new ENV variable which contains the private key required whenever you edit or query credentials. Example: For the development environment, the new ENV variable DEVELOPMENT_CREDENTIALS_KEY replaces the old ENV variable BRIDGETOWN_DEVELOPMENT_KEY.

Please note that Dry::Credentials does not support unified environments (one config/credentials.yml.enc for both development and production) anymore!

Also, nested credentials have to be queried differently now and thus you might have to update your Bridgetown site accordingly. Given the example credentials from the Usage section below:

# Queries on version 0.x.x
Bridgetown.credentials.foo                            # => "bar"
Bridgetown.credentials.aws[:access_key_id]            # => "awsXid"
Bridgetown.credentials.google.dig((:maps, :api_key)   # => "goomXkey"

# Queries on version 1.x.x
Bridgetown.credentials.foo                            # => "bar"
Bridgetown.credentials.aws.access_key_id              # => "awsXid"
Bridgetown.credentials.google.maps.api_key            # => "goomXkey"

Usage

First Time

Make sure you have set the EDITOR variable to your favourite editor and then create a new credentials file:

echo $EDITOR
bin/bridgetown credentials edit

You might want to add something along the lines of:

foo: bar
aws:
  access_key_id: awsXid
  secret_access_key: awsXsecret
google:
  maps:
    api_key: goomXkey
  places:
    api_key: goopXkey

After saving, the private key required to encrypt/decrypt the credentials is printed this first time only. Make sure you store this information in a safe place, you will need it in the future.

The credentials you've edited above has been written to config/credentials/development.yml.enc and will be loaded when Bridgetown is in development mode.

To edit the credentials for production mode:

bin/bridgetown credentials edit -e production

To edit or query credentials from now on, the corresponding ENV variable with the private key has to be set:

export DEVELOPMENT_CREDENTIALS_KEY="4c87...af93"
export PRODUCTION_CREDENTIALS_KEY="92bb...820f"

Edit

The command is the same as the first time:

bin/bridgetown credentials edit
bin/bridgetown credentials edit -e production

Query

Throughout the Bridgetown stack, you can now use the credentials as follows:

Bridgetown.credentials.foo                   # => "bar"
Bridgetown.credentials.aws.access_key_id     # => "awsXid"
Bridgetown.credentials.google.maps.api_key   # => "goomXkey"

Tests

  • bundle exec rake test to run the test suite
  • script/cibuild to validate with Rubocop and Minitest together

Development

You're welcome to submit issues and contribute code by forking the project and submitting pull requests.