Read secrets from an external secret manager

Config for provider command with sops, Doppler, Infisical, Vault, AWS Secrets Manager, 1Password, Bitwarden, and a plain dotenv file.

Read as MarkdownEdit on GitHub

With provider: command, yoink runs a command and reads the secrets bundle from its stdout. Use the section for the secret manager that you already run.

Before you start

  • Make sure that the command prints only the bundle to stdout. Send diagnostics to stderr (>&2).
  • Make sure that the auth token of the tool is in the environment. yoink forwards only an allowlist of variables to the command.
  • If you need pipes or env-var expansion, put the call in a shell script. yoink runs the command without a shell.

For the dotenv and JSON bundle formats, see the format reference.

sops

  1. Run brew install sops on your laptop and on the CI runner.
  2. Configure .sops.yaml with the encryption recipients (for example an age key or a KMS ARN).
  3. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["sops", "-d", "--output-type=dotenv", "secrets.enc.yaml"]

To edit the secrets, run sops edit secrets.enc.yaml. yoink does not wrap this command.

For the trade-offs between sops and provider: age, see Secrets.

Doppler

  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["doppler", "secrets", "download", "--no-file", "--format", "env"]
  1. In CI, set the DOPPLER_TOKEN env var to a service token that has the scope of the correct config.

The runner does not need doppler login.

Infisical CLI

  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command:
    - infisical
    - export
    - --env=prod
    - --projectId=YOUR_PROJECT_ID
    - --format=dotenv
  1. For auth, set INFISICAL_TOKEN (machine identity) or use a logged-in infisical login session.
  2. If the instance is self-hosted, add --domain=https://infisical.your.domain to the argv.

PEM certs and private keys pass through unchanged. Infisical emits them in single quotes across multiple lines, and the dotenv parser of yoink reads that shape. A wrapper script is not necessary.

HashiCorp Vault

  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["sh", "-c", "vault kv get -format=json -field=data secret/yoink/prod"]
  format: json
  1. For auth, set VAULT_ADDR and VAULT_TOKEN, or use AWS or OIDC roles.

-field=data makes Vault print the flat KV data as one JSON object on stdout.

AWS Secrets Manager

  1. Store the value in the SecretString as a JSON object ({"DB_URL":"...","API_KEY":"..."}) or as a dotenv blob.
  2. Add this config to yoink.yaml:
secrets:
  provider: command
  command:
    - sh
    - -c
    - "aws secretsmanager get-secret-value --secret-id yoink/prod --query SecretString --output text"
  format: auto

Auth comes from the IAM role of the runner.

1Password

1Password holds structured items, not a flat namespace. A small wrapper script emits them as dotenv.

  1. Write the wrapper script:
# bin/yoink-secrets.sh — operator-owned, gitignored alongside yoink.yaml
#!/usr/bin/env bash
set -euo pipefail
op read "op://Engineering/yoink-prod/DATABASE_URL"        | sed 's/^/DATABASE_URL=/'
op read "op://Engineering/yoink-prod/JWT_SIGNING_KEY"     | sed 's/^/JWT_SIGNING_KEY=/'
op read "op://Engineering/yoink-prod/STRIPE_SECRET_KEY"   | sed 's/^/STRIPE_SECRET_KEY=/'
  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["./bin/yoink-secrets.sh"]
  1. In CI, set the OP_SERVICE_ACCOUNT_TOKEN env var to the token of a 1Password service account.

As an alternative to the wrapper script, use op inject with a template:

# secrets.tpl
DATABASE_URL={{ op://Engineering/yoink-prod/DATABASE_URL }}
JWT_SIGNING_KEY={{ op://Engineering/yoink-prod/JWT_SIGNING_KEY }}
secrets:
  provider: command
  command: ["op", "inject", "-i", "secrets.tpl"]

Bitwarden

  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["bws", "secret", "list", "PROJECT_UUID", "--output", "env"]
  1. For auth, set BWS_ACCESS_TOKEN.

A static dotenv file (for local development)

Use this config to keep the provider: command schema in local development, with a plain file as the source.

  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["cat", ".env.local"]
  1. Add .env.local to .gitignore.

Layered: command on top of age

yoink does not merge providers. A wrapper script that prints the two bundles in sequence gives the same result.

yoink secrets show works only with provider: age. Thus the age block goes into a second config file.

  1. Write a second config file that holds only the age block:
# yoink.age.yaml
secrets:
  provider: age
  recipients: [age1…]
  1. Write the wrapper script:
# bin/yoink-secrets.sh
yoink --config yoink.age.yaml secrets show --reveal   # age-decrypted dotenv (committed)
op inject -i ops-overrides.tpl                        # 1Password-managed runtime tweaks
  1. Add this config to yoink.yaml:
secrets:
  provider: command
  command: ["./bin/yoink-secrets.sh"]

Later lines override earlier lines, because the dotenv parser keeps the last value for each key.

yoink does not forward YOINK_AGE_KEY or YOINK_AGE_KEY_FILE to the command. The age identity must be in ~/.config/yoink/keys/, or the script must set the variable.

Make sure that it works

Run yoink up. yoink runs the command one time for each yoink up and injects the values as env vars into the containers.

If the command exits non-zero, yoink stops and shows the stderr of the command. If the bundle is malformed, yoink stops with a parse error.

See also

Type a flag, a config field, or a task.