Secrets

The Vault keeps passwords, keys, tokens and private files in one place. Every value is encrypted, always shown masked, and can differ for each environment (production, staging…). Your application reads it with a command, without you copying it by hand.

Where a secret goes

The Vault has three spaces. Before saving, ask yourself who needs the value:

Each space has two tabs: Variables (name and value pairs) and Files (for example a certificate or a config file, up to 10 MB).

Save a secret

1. Open Vault and pick the right space.
2. Add the variable with its name, then type the value for each environment where it is needed.
3. If it is an organization secret, delegate it to the projects that should use it. You can revoke it whenever you want. A project secret is ready to use as is.

In the project secrets table the rows are locked: press the padlock at the end of a row to change it. That way you don't change by mistake something you were only looking at.

From the terminal you do the same with cyi secrets set (project), cyi shared set (organization) and cyi personal set (personal). To load many at once from a .env or JSON file there is cyi secrets import. See the CLI.

Use secrets in your app

The command starts your app with the secrets already inside, as environment variables. It writes nothing to disk:

cyi run -p acme-api -e production -- bundle exec rails server

For your personal secrets: cyi personal run -- <command>.

If you really need a file, cyi secrets download -p acme-api -e production --out .env writes one. cyi secrets get prints the value of a single secret. At the bottom of every secrets page you find the command already filled in.

History and rollback

Every change of value creates a new version. Open the secret's history, look at the earlier values and restore the right one.

Who read what

Every read is recorded: those made from the page and those made from the terminal. The same goes for changes, deletions and syncs.

• For one project: the Access log tab in its secrets.
• For the whole organization: Vault → History, with filters by action, project and environment.

An attempt to read an environment you are not allowed to see is recorded too, as Blocked. To be alerted about reads or attempts, create a rule with the Secret read or Secret access denied event: see Alerts.

A different value for one person

Sometimes one person needs a value of their own: their copy of the database, their test inbox for emails. Tailored values change it for them alone.

1. Open the project, its secrets tab, then Tailored values.
2. Pick the person, the environment and the exact variable name. The person must already be able to read those secrets.
3. Type the value and save. From then on they get it when they download the secrets, with nothing to do.
4. When it is no longer needed, remove it: the person goes back to the normal value straight away.

Good to know:

• Only whoever manages the project's secrets assigns them. The person receiving the value cannot change or remove it.
• The list shows who was given what, never the value.
• GitHub always receives the project's normal value, never a tailored one.
• A tailored value does not open an environment the person cannot see.

Two-person approval

On the environments you choose, a change does not go through right away: it waits until someone else approves it.

1. In the project settings, turn on Two-person approval for secrets.
2. On the environment to protect (for example production), turn on approval too.

From then on, whoever changes or deletes a secret in that environment leaves a request. The request shows up in Approvals for whoever can decide it. Whoever made it cannot approve it alone. From the terminal: cyi vault requests list, cyi vault requests approve <id> and cyi vault requests reject <id> --reason "…".

Sync with GitHub

If the project has a repository connected through the GitHub App, the Vault's secrets end up in the repository's Environments. Builds find them ready.

• With sync turned on, every change goes out by itself.
• To start it by hand: Sync now in the project's GitHub tab, or cyi secrets sync -p acme-api.
• CloseYourIt removes from GitHub only the secrets it put there. Secrets set by hand on the repository stay.
• If a sync fails, you get a notification with the reason.

The same value in several projects

If two or more projects keep the same value, even under different names, CloseYourIt tells you. The comparison happens without anyone reading the values.

1. The suggestion shows up in Vault → Needs fixing and in the secrets of the projects involved.
2. Open it: you see which projects hold that value and under which name.
3. Pick the name it will have in the organization. Each project can keep reading it under today's name.
4. Confirm. The value becomes an organization secret and every project receives it right away, with no change to its code.

Without your confirmation nothing changes. If two projects share a value by accident, press Stop suggesting.