Machines and CI

A CI runner, deploy host, or scheduled job can use fd0 with its own identity instead of a person's unlocked vault or a copied secret. The machine identity is an ordinary fd0 identity that unlocks with a key file and is a member of only the scopes it needs.

Create the machine identity

Run these as a dedicated service user that owns the identity's directory. Separate directories under one user do not keep processes apart. Create the key outside fd0, for example as a systemd credential.

$ export FD0_HOME=/var/lib/ci/fd0
$ umask 077; head -c 32 /dev/urandom | base64 > /etc/ci/fd0.key
$ fd0 init --key-file /etc/ci/fd0.key
$ fd0 unlock --key-file /etc/ci/fd0.key

The key file must be a regular file owned by that user or root, not readable by group or others, and hold at least 32 bytes. Use - to read it from stdin. With a key file, fd0 never falls back to a prompt.

Pin the server

# on your device: the server and safety number it pinned
$ fd0 status --servers

# on the machine
$ fd0 sync --pin "12345 67890 ..."

Take the safety number from fd0 status --servers on a device that already uses the same server. --pin pins the server only if the numbers match, and refuses a server whose number differs later. Background sync never pins a server by itself.

Give it access

# on the machine
$ fd0 card export

# on your device
$ fd0 card import "fd0://card/..." --label ci-runner
$ fd0 scope add-member ci-runner --scope deploy --role reader
$ fd0 sync

# on the machine
$ fd0 sync

Add the machine as reader, or writer if it rotates the values it uses. Neither can change who has access; see roles. Prefer a scope that holds only this machine's credentials, because every member can read everything in the scope.

Use it in a job

$ fd0 unlock --key-file "$CREDENTIALS_DIRECTORY/fd0.key"
$ fd0 sync
$ fd0 run --service app --scope deploy -- ./deploy.sh

fd0 unlock --key-file returns at once when the vault is already unlocked and unlocks again after a timeout, so run it at the start of every job.

Revoke a machine

Remove it from its scopes with fd0 scope remove-member ci-runner --scope deploy, then rotate every value it could read. One identity per machine and purpose; never copy its fd0 directory to another host.