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.jsonfrom 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.jsonand 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.