Restricting a CI Deploy Key to One Job
7 min read
Most CI deploy keys start life the same way. You generate a key with no passphrase, paste the private half into a pipeline variable, append the public half to /root/.ssh/authorized_keys on the web server, and the deploy goes green. Job done.
What you have actually built is a passwordless root shell that anyone who can read that variable can use, from anywhere, for anything. The pipeline only ever runs one deploy, but the key will happily open a login shell, forward ports into your private network, or cat /etc/shadow. And because it works, nobody looks at it again, which is how the key from the CI system you migrated away from last year is still installed next to the new one.
authorized_keys can fix all of that on a single line. The key keeps working for the one job it exists to do and refuses everything else.
The options that matter
Each line of authorized_keys can be prefixed with comma-separated options that apply only to that key. Three do the heavy lifting:
restrictturns off everything optional in one word: port, agent and X11 forwarding, PTY allocation, and execution of~/.ssh/rc. It was added in OpenSSH 7.2 precisely so you don't have to remember theno-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-ptylist, and it will also cover any new capability added to sshd later. Individual features can be switched back on after it (restrict,pty) if a key genuinely needs one.command="..."forces the command. Whatever the client asks to run is ignored, and sshd runs this instead. The client's request is still available to the forced command in$SSH_ORIGINAL_COMMAND, so a wrapper can inspect it or just log it. The forced command also overrides subsystem requests, so the key cannot be used forsftporscpeither.from="..."limits which source addresses may use the key. It takes a comma-separated list of hostnames, address patterns and CIDR blocks. A stolen key is a lot less useful if it only authenticates from your runner's subnet.
A restricted deploy line looks like this:
restrict,command="/usr/local/bin/receive-site",from="10.0.20.0/24" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... ci-deploy@runner 2026-11
Put a date in the key comment. It is the only metadata the file has, and you will want it the day you are deciding whether a key is still in use.
Design the deploy so it can be restricted
A forced command means the key can do exactly one thing, and here is the catch: most pipelines don't deploy in one thing. A typical static-site deploy is three separate SSH sessions:
tar -czf - -C dist . | ssh web "rm -rf /tmp/stage && mkdir /tmp/stage && tar -xzf - -C /tmp/stage"
ssh web "test -s /tmp/stage/index.html"
ssh web "rsync -a --delete /tmp/stage/ /var/www/example.com/"
Each line sends a different shell command, so the key needs a general-purpose shell, and the moment it has one, command= cannot be applied without breaking the deploy. This is why unrestricted deploy keys are so common. Nobody chose it; the pipeline shape required it.
The fix is to move the deploy logic onto the server and give the client nothing to say. The client streams a tarball, and the server decides what happens to it:
tar -czf - -C dist . | ssh deploy@web
No command at all. Whatever happens next is defined server-side, in a file you can review.
The receiving script
Install this as /usr/local/bin/receive-site, owned by root and mode 755, so the deploy user can run it but not edit it:
#!/bin/sh
# Forced command for the CI deploy key. Reads a gzipped tarball of the
# built site on stdin, validates it, then swaps it into the webroot.
# Whatever the client asked to run is in $SSH_ORIGINAL_COMMAND and is ignored.
set -eu
WEBROOT=/var/www/example.com
STAGE=$(mktemp -d "${WEBROOT%/*}/.stage.XXXXXX")
trap 'rm -rf "$STAGE"' EXIT
logger -t receive-site "deploy from ${SSH_CLIENT%% *}, ignored command: ${SSH_ORIGINAL_COMMAND:-none}" || true
tar -xzf - -C "$STAGE"
for f in index.html sitemap.xml; do
[ -s "$STAGE/$f" ] || { echo "staged tree is missing $f, refusing to deploy" >&2; exit 1; }
done
rsync -a --delete "$STAGE/" "$WEBROOT/"
echo "deployed $(find "$WEBROOT" -type f | wc -l) files"
A few details are doing real work here:
- The validation runs before
rsync --delete.tarcan exit cleanly on a truncated stream, and a partial tree plus--deleteremoves every file that failed to arrive. Checking the staged tree on the server, after the transfer, is the only place that catches a transfer problem. Add whatever files your site cannot live without to that loop, or a minimum page count. - The stage directory sits next to the webroot, not in
/tmp, so it is on the same filesystem and thersyncis a local copy rather than a cross-device one.mktemp -dmeans two overlapping deploys cannot clobber each other's staging area, and thetrapcleans up on any exit, including a failed validation. - Requested commands get logged. A legitimate pipeline never sends one, so a non-empty
$SSH_ORIGINAL_COMMANDin the log is someone trying the key for something it was not issued for.
The script also lets you stop deploying as root. Create a dedicated user that owns the webroot and nothing else:
useradd -m -s /bin/sh deploy
chown -R deploy: /var/www/example.com
Give it a real shell. sshd runs the forced command through the user's login shell ($SHELL -c "<command>"), so a user whose shell is /sbin/nologin cannot run the forced command either, and the deploy fails in a confusing way. The restrict and command= options are what stop interactive use, not the shell.
Then the key goes in /home/deploy/.ssh/authorized_keys, not root's.
Prove it refuses what it should
Don't trust the line until you have watched it say no. From a host inside the from= range, run a normal deploy first:
tar -czf - -C dist . | ssh -i ci_key deploy@web
deployed 412 files
Now try to use the key for something else. The command is ignored, the script runs, finds an empty stream, and refuses:
ssh -i ci_key deploy@web 'cat /etc/shadow' < /dev/null
staged tree is missing index.html, refusing to deploy
Ask for an interactive session:
ssh -tt -i ci_key deploy@web < /dev/null
PTY allocation request failed on channel 0
Try a port forward into the network behind the server. The tunnel appears to open, because the local listener is the client's, but the server refuses the first connection through it, and its log says so:
ssh -i ci_key -N -L 8080:10.0.20.5:80 deploy@web
refused local port forward: originator 127.0.0.1 port 54626, target 10.0.20.5 port 80
Finally, from a machine outside the from= range, the key does not authenticate at all:
deploy@web: Permission denied (publickey).
and the server log tells you exactly why:
Authentication tried for deploy with correct key but not from a permitted host (host=203.0.113.50, ip=203.0.113.50, required=10.0.20.0/24).
That last line is worth having in your alerting. It means somebody has the private key and is using it from somewhere unexpected.
When plain rsync is enough
If your deploy really is a single rsync with no server-side validation, you don't need a custom script. rrsync, which ships with rsync, is a forced command that only accepts rsync's server-side invocation and confines it to one directory:
restrict,command="rrsync -wo /var/www/example.com",from="10.0.20.0/24" ssh-ed25519 AAAA... ci-deploy@runner 2026-11
-wo makes the area write-only, so the key can push but not read the tree back. Client-side paths become relative to the confined directory, so the client syncs to deploy@web: rather than to a full path. Distributions package it differently (Debian ships it in /usr/bin, Gentoo puts it behind the rrsync USE flag), so check command -v rrsync before you rely on it. The wrapper script above is still the better fit whenever --delete is involved, because rrsync has nowhere to put a check before the delete runs.
Audit what is already installed
Restricting the new key does nothing about the old ones. ssh-keygen reads authorized_keys files directly, options and all, and prints one fingerprint per key:
ssh-keygen -lf /root/.ssh/authorized_keys
ssh-keygen -lf /home/deploy/.ssh/authorized_keys
256 SHA256:LGkRh3yMHAcucTLpjVkU6KLXoMOuczrS/nQu/alZ5JE ci-deploy@runner 2026-11 (ED25519)
256 SHA256:9vQm0b1q7c2hZxR4sT8wKd3nE6yLpA0uJfGiHc5oVbM github-actions-deploy (ED25519)
Match each fingerprint against the key your pipeline actually holds, then delete every line you cannot account for. The sshd log records the fingerprint of every key that authenticates (Accepted publickey for deploy from ... ED25519 SHA256:...), so a fingerprint that has not appeared in months of logs belongs to a system that no longer deploys.
Checklist for a deploy key
- Dedicated user that owns the webroot, not root.
restricton the key line, so no forwarding, no PTY, no~/.ssh/rc.command=pointing at a root-owned script the deploy user cannot edit.from=limited to the runner's address or subnet.- Validation of the staged tree on the server, before anything runs
--delete. - Host key pinned on the client (
StrictHostKeyChecking yeswith a committedknown_hosts), so the key is never offered to an impostor. - A dated comment on every key, and no lines in
authorized_keysyou cannot name.