keyshroud

CI and Docker

A CI job or a Docker build has no keychain and nobody to type a passphrase. The pattern is the same everywhere: an encrypted vault file travels with the job, and the CI's own secret store holds one thing, the passphrase that opens it. The job's log shows <redacted:NAME> wherever a value is printed.

If your CI already injects secrets as environment variables and no agent runs there, you may not need keyshroud in CI at all. This guide is for when you want one .env.refs to work on laptops and in CI alike, or masked logs.

1. Create a vault for CI

On your machine, in a terminal. A directory of its own keeps it apart from your personal vault:

export KEYSHROUD_CONFIG_DIR=~/.config/keyshroud-ci
KEYSHROUD_VAULT_KEY=passphrase keyshroud unlock      # choose a passphrase: 12+ characters, typed twice
keyshroud add --env DEPLOY_TOKEN --item "ci DEPLOY_TOKEN"
keyshroud add --env NPM_TOKEN --item "ci NPM_TOKEN"
unset KEYSHROUD_CONFIG_DIR

Then put two things in place:

  • vault.json from that directory goes into the repository (or an artifact). It is encrypted with AES-256-GCM under a key derived from the passphrase, item names included. Copy only that file, none of the others beside it: mkdir -p ci && cp ~/.config/keyshroud-ci/vault.json ci/vault.json
  • The passphrase goes into the CI's secret store as KEYSHROUD_PASSPHRASE.

And a .env.refs in the repository that names the items:

DEPLOY_TOKEN=keyshroud://ci DEPLOY_TOKEN
NPM_TOKEN=keyshroud://ci NPM_TOKEN

To add or rotate a secret later, do it in that directory again and commit the new vault.json.

2. In the job

npm i -g keyshroud
mkdir -p ~/.config/keyshroud && cp ci/vault.json ~/.config/keyshroud/
printf '%s' "$KEYSHROUD_PASSPHRASE" | keyshroud unlock --stdin   # a session of 30 minutes
keyshroud run --refs .env.refs -- npm run deploy

unlock --stdin only opens an existing passphrase vault; a new passphrase is always chosen in a terminal. keyshroud run does not hand KEYSHROUD_PASSPHRASE on to the command it starts, and masks its value in the output like any other secret.

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 22 }
      - run: npm i -g keyshroud
      - name: Open the vault
        env:
          KEYSHROUD_PASSPHRASE: ${{ secrets.KEYSHROUD_PASSPHRASE }}
        run: |
          mkdir -p ~/.config/keyshroud && cp ci/vault.json ~/.config/keyshroud/
          printf '%s' "$KEYSHROUD_PASSPHRASE" | keyshroud unlock --stdin
      - run: keyshroud run --refs .env.refs -- npm run deploy

Later steps in the same job use the open session; they do not need the passphrase again. A job that runs longer than 30 minutes before it needs a secret unlocks again at that point, or sets KEYSHROUD_SESSION_TTL_MS higher.

Docker builds

Pass the passphrase as a BuildKit secret, so it is in no layer and no docker history, and open, use and lock the vault inside one RUN:

# syntax=docker/dockerfile:1
FROM node:22-slim
RUN npm i -g keyshroud
WORKDIR /app
COPY . .
RUN --mount=type=secret,id=keyshroud_passphrase \
    mkdir -p ~/.config/keyshroud && cp ci/vault.json ~/.config/keyshroud/ && \
    keyshroud unlock --stdin < /run/secrets/keyshroud_passphrase && \
    keyshroud run --refs .env.refs -- npm run build && \
    keyshroud lock
docker build --secret id=keyshroud_passphrase,env=KEYSHROUD_PASSPHRASE .

keyshroud lock at the end matters: an open session is a file beside the vault, and without the lock it would be saved in that layer. A value your build writes into its own output (a bundled API key, a generated config) is in the image regardless: keyshroud masks what is printed, not what is built.

A container at run time

A container is a new machine: it has no keychain, so the vault there is a passphrase vault. Mount the vault file, pass the passphrase the way your platform passes secrets, and start the service through keyshroud:

printf '%s' "$KEYSHROUD_PASSPHRASE" | keyshroud unlock --stdin && exec keyshroud run --refs .env.refs -- node server.js

A server you reach over SSH

Create a passphrase vault there and run keyshroud unlock --unattended once in a terminal: that session has no time limit, until keyshroud lock.

Limits

  • Anyone who has both vault.json and the passphrase has every secret in it. Keep a CI vault small: only what the jobs need, not a copy of your own vault.
  • A fork's pull request does not get your CI secrets, so it cannot open the vault. That is what you want.
  • These steps are checked on Linux (a GitHub-style job and a real docker build). They are not tested on Windows runners.

Edit this page on GitHub · Markdown