secrets.json

Gage profiles, which are defined in gage.toml, may contain references to secrets. A secret is a value that is encrypted and accessible only by authorized users.

Encrypted secrets are stored in a JSON-formatted file. The secrets file must be explicitly specify for a profile. You’re free to use any name for a secrets file. By convention, if a single secrets file is used for a project, it’s named secrets.json.

Secrets are encrypted by the sops program.

SOPS

SOPS is a command line tool that supports editing of encrypted files. It supports a variety of formats but Gage uses JSON for secrets access.

The SOPS project provides downloadable binaries and packages for most platforms. If you have any issues installing SOPS for your system, please open an issue with the Gage CLI project and we’ll try to help.

Create secrets.json

To create a new secrets.json file, run sops with an encryption scheme. SOPS supports a variety of schemes including GPG, age, and secret stores for AWS, GPG, Azure, and Hashicorp.

GPG auth

Use the -p for each GPG key you want to authorize.

sops -p <key> [-p <key>...] secret.json

Each <key> is the GPG public key fingerprint for a user you want to grant access to the secrets in the file. To list available fingerprints, run gpg --list-keys. The fingerprint for each user is listed under pub.

age auth

age is a generally available encryption tool. It’s often used as an alternative to GPG/PGP.

To create secrets.json for age recipients, use the -a option with the sops command.

sops -a <key> [-a <key>...] secrets.json

Each <key> is a public key for a user you want to grant access to the secrets.

Other encryption schemes

See SOPS usage for details on using other encryption schemes.

Modify secrets.json

You must use sops to edit secrets.json.

sops secrets.json

SOPS decrypts the secrets for your editor. When you save the file, SOPS re-encrypts the new values. It preserves the access rights defined when you created secrets.json.

To modify authorized users, use the sops options starting with --add- and --rm- to add and remove users respectively. Refer to sops --help for details.

sops --help

Secrets in gage.toml

A secret is referenced in a profile environment variable using the syntax {REF} where REF is a dot-separated path associated with a value defined in secrets.json.

For example, if your secrets.json file looks like this:

{
  "openai": {
    "api_key": "*****"
  },
  "anthropic": {
    "api_key": "*****"
  }
}

The API key for OpenAI would be referenced as {openai.api_key}.

[profiles.default]

secrets = "secrets.json"
env.OPENAI_API_KEY = "{openai.api_key}"
env.ANTHROPIC_API_KEY = "{anthropic.api_key}"

To enable secrets support for a profile, you must specify the file using the secrets attribute. Gage will not apply secrets to profile env values without this explicit setting.