Git for managing code, Keystone for managing secrets.

In a decade Git became the de facto version control system for most companies, including giants like Google, Facebook or Microsoft. It changed the way to manage development projects. Now is the time to step forward and handle secrets in a similar fashion.

Why you should stop sharing environment variables over email or chat apps?

, we had bad behaviours when handling secrets at my web agency.

Most of the time we were sharing sensitive information like API tokens or database passwords in our private Slack space. Meaning Slack has copies of that information. Storing secrets in third parties where you don’t have any control is not something you want. Afterall any online service can be hacked in a way or another.


Some are even using plain emails which open other kind of problems. The receiver can forward the email to parties that should not get access to that information. Also your email is transiting through different servers: your provider, the receiver provider, spam filters and other potential analytics tools in between.

That's far too many places where your private data can be archived.

It's hard to keep secrets in sync with your codebase.

Your code will not work without its applications tokens. Worst, your code evolves with time and so does your secrets. New tokens appear, passwords are changed. Your teammates need to stay in sync.
It's even more complex when we think about deployment where it's common to have different environments like staging and production. Both have tokens and database credentials
but they are different

What could happen when you are not in sync?

As a developer:
unreliable or totally broken development environment
wasting time to understand why your codebase is not working while it is for your teammates

In a staging/production context:
missing secrets could create downtimes or hard-to-find bugs because, well... they're not.
losing customer data by setting the wrong database credentials

From our experience as a web agency, as soon as you are working with another developer it's very likely to happen. And it can become a terrible situation when the only person with the latest credentials is
unreachable for days

Keystone is Git new best friend

Keystone is sharing some common traits with Git.

Besides being open-source, it’s distributed. It doesn’t rely on a centralized server. Developers are able to add secrets along the code and stay in sync with others. A config file that you need to commit makes the link between your project's source code and the secrets it needs. Secrets can be any text files: database credentials, dotenv files, yaml configurations, google credentials stored as json and so on.

They sit with your code at the place you want.

In Git you checkout branches. In Keystone you checkout environments.

Environment variables are always related to a specific environment.

In development you could use a fake smtp server like
while in production or staging you will use the real thing, yet with different tokens. So instead of branches you have environments. You can create as many as you want.
are a good start. When you push, environment variables versioned on Keystone are stored on a private locker.

This private locker is yours. You are the only one able to write on it and all the data is encrypted for you and your teammates if any.

Keystone is built on Blockstack, a decentralized computing network and app ecosystem. It handles authentication, encryption and storage. You can learn more at

Below is a basic flowchart describing a workflow between 3 developers with different roles.
Untitled - Keystone basics.jpg

Creating new workflows

Having fun in local development

Now that we are used to Keystone, we are looking at ways to make it even more cool to use. The first thing we did was integrating the command
ks status
into our
templates. We wanted to answer 2 questions during development: from which environment our secrets are coming? Are there any secrets or tokens we should push? Now we have a view at Git and Keystone state in the blink of an eye.

You can find the zsh and bash recipe on Github:

We could go one step further and automate pull and push commands using Git hooks. After a successful
git pull
we can trigger a
ks pull
to sync our secrets. In the same manner, we can trigger a
ks push
after a successful
git push
in order to avoid missing credentials related to that commit. Even better we could check before a
git pull or git push
that your Keystone state is clean!

Keeping our CI workflow up-to-date

Development is one thing but soon after comes deployment. In our case we are used to Github Actions. We wanted to trigger a command that could retrieve all our production application secrets at each deploy. That's a feature Keystone has. With the command
ks share
you get a special token which is able to pull all files from a defined environment.

A tutorial will come soon. In the meantime you can learn more here:

As you can see, there's tons of new workflows to try and we hope you will find Keystone useful. We are eager to get your feedback and your own workflows.

👉Check the project on Github

Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
) instead.