CI deploys without a deploy key
Part 4 of the SSH series that starts with Why SSH certificates.
My websites are built by Forgejo Actions. After a push to main, a job builds a container image, pushes it to the registry and logs in to the web host by SSH. There it runs podman auto-update, which pulls the new image and restarts the site.
That login used a deploy key: a private SSH key, stored as a secret in Forgejo, valid forever. This post replaces it with a certificate that a job gets for itself, valid for five minutes, and only for pushes to main. Forgejo stores no secret for it.
How a job proves who it is
Forgejo Actions can give a job an OpenID Connect ID token, like GitHub Actions does (I run Forgejo 15). It is a JWT, signed by Forgejo, with claims about the job. Shortened:
{
"iss": "https://git.example.org/api/actions",
"aud": "https://bao.example.net",
"sub": "repo:alice/blog:ref:refs/heads/main",
"repository": "alice/blog",
"exp": 1763222400
}
Anybody can check the signature with Forgejo’s public keys, which it publishes at https://git.example.org/api/actions/.well-known/openid-configuration. Bao’s jwt auth method does exactly that, and then it checks the claims.
sub is the claim to bind on. For a push it is repo:<repo>:ref:<ref>. For a pull request it is repo:<repo>:pull_request. A pull request from a fork can run the workflow, but it can never get a deploy certificate.
Step 1: Bao’s side
Three parts, all in the configuration script from the OpenBao post.
The role for the certificate, with the command already in it:
user_role deploy-websites deploy-websites 5m "" '{"force-command": "podman auto-update"}'
A policy that can sign that role, and revoke its own token:
bao policy write deploy-websites - <<'HCL'
# CI deploys of the sites (jwt login): one 5-minute cert per job
path "ssh-user/sign/deploy-websites" { capabilities = ["update"] }
path "auth/token/revoke-self" { capabilities = ["update"] }
HCL
The jwt login, with Forgejo as the issuer, and a role that binds the claims:
auth jwt jwt
bao write auth/jwt/config oidc_discovery_url=https://git.example.org/api/actions \
bound_issuer=https://git.example.org/api/actions >/dev/null
bao write auth/jwt/role/websites - >/dev/null <<'JSON'
{
"role_type": "jwt",
"bound_audiences": "https://bao.example.net",
"user_claim": "repository",
"bound_claims_type": "string",
"bound_claims": {"sub": [
"repo:alice/blog:ref:refs/heads/main",
"repo:alice/shop:ref:refs/heads/main",
"repo:alice/portfolio:ref:refs/heads/main"
]},
"token_policies": "deploy-websites",
"token_no_default_policy": true,
"token_ttl": "5m",
"token_max_ttl": "5m"
}
JSON
The fields that matter:
bound_audiences: the job must ask for a token for Bao. A token that the job got for another service is refused.bound_claimsonsub: only pushes tomainof these three repositories. Another branch, a tag or a pull request gets “claim is not in the bound claims”.user_claim: repository: the Bao token’s display name becomesjwt-alice/blog. The certificate’s key ID is thenjwt-alice/blog-deploy-websites, and that is what the web host logs for each deploy.token_no_default_policy: Bao’sdefaultpolicy lets a token look itself up and use the cubbyhole, among other things. A CI token needs none of that. Without the default policy it also cannot revoke itself, so thedeploy-websitespolicy grantsrevoke-selfexplicitly.
Step 2: the web host’s side
The principals file for the account that runs the sites has the option, as shown in the previous post:
# group_vars/websites.yml
ssh_principals:
svc: [alice, 'restrict,command="podman auto-update" deploy-websites']
restrict turns off everything: a pty, port forwarding, agent forwarding, X11. command= forces the command. The CA sets force-command too, but the host does not depend on that.
Step 3: the network
The CI runner runs on my mail host, on the internet. Bao runs at home and is not on the internet. The runner reaches the home server through the monitoring tunnel from the monitoring post. That tunnel ends in the hub’s block zone, where the VPS cannot open any connection.
I did not want to open port 443 on the hub for the runner. Port 443 is Traefik, and Traefik routes to every app on the home server. So Traefik gets an extra entrypoint, and only Bao’s router uses it:
# traefik.yml on home1
entryPoints:
https:
address: ":443"
# Only OpenBao's router uses this entrypoint: the CI runner may reach Bao and nothing else
bao:
address: ":8443"
# traefik.container: publish it
PublishPort=8443:8443/tcp
# openbao.container: the router listens on both
Label=traefik.http.routers.openbao.entrypoints=https,bao
The hub’s firewall then has one exception, for the runner’s tunnel address and this port:
# host_vars/home1.yml
wg_hub_block_exceptions:
- {source: 10.99.0.11, port: 8443/tcp}
From the runner host, the result:
curl -s -o /dev/null -w '%{http_code}\n' https://bao.example.net:8443/v1/sys/health # 200
curl -s -o /dev/null -w '%{http_code}\n' --resolve grafana.example.net:8443:10.99.0.1 \
https://grafana.example.net:8443/ # 404
curl -s -m 5 https://bao.example.net/ || echo blocked # blocked
Another app’s name on 8443 gives a 404, because no other router listens there. Port 443 stays blocked.
The runner needs the name bao.example.net to resolve to the tunnel address. It does, because the public record points there (see the OpenBao post).
Step 4: the workflow
env:
DEPLOY_HOST: vps2.example.org
DEPLOY_USER: svc
BAO_ADDR: https://bao.example.net:8443
# The host CA: the web host shows a certificate signed by it, no pinned host key
HOST_CA: "ssh-ed25519 AAAA...host-ca-public-key..."
jobs:
# test and build jobs as before ...
deploy:
runs-on: ubuntu-latest
needs: build
if: github.ref == 'refs/heads/main'
# The job's ID token (repository, ref) is its login at OpenBao
enable-openid-connect: true
steps:
- name: Trigger podman auto-update
run: |
dir=$(mktemp -d) && trap 'rm -rf "$dir"' EXIT
# 1. the job's ID token, for Bao as the audience
jwt=$(curl -fsS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://bao.example.net" | jq -er .value)
echo "::add-mask::$jwt"
# 2. log in to Bao with it
token=$(jq -n --arg jwt "$jwt" '{role: "websites", jwt: $jwt}' \
| curl -fsS -X POST -d @- "$BAO_ADDR/v1/auth/jwt/login" | jq -er .auth.client_token)
echo "::add-mask::$token"
# 3. a throwaway key, signed for five minutes
ssh-keygen -q -t ed25519 -N '' -C "$GITHUB_REPOSITORY" -f "$dir/key"
jq -n --rawfile k "$dir/key.pub" '{public_key: $k}' \
| curl -fsS -X POST -H "X-Vault-Token: $token" -d @- "$BAO_ADDR/v1/ssh-user/sign/deploy-websites" \
| jq -er .data.signed_key > "$dir/key-cert.pub"
# 4. the token is not needed any more
curl -fsS -X POST -H "X-Vault-Token: $token" "$BAO_ADDR/v1/auth/token/revoke-self"
ssh-keygen -Lf "$dir/key-cert.pub" | sed -n '/Key ID/p;/Valid/p'
# 5. the host is checked through the CA, then: podman auto-update, nothing else
echo "@cert-authority $DEPLOY_HOST $HOST_CA" > "$dir/known_hosts"
ssh -i "$dir/key" -o IdentitiesOnly=yes -o UserKnownHostsFile="$dir/known_hosts" \
-o StrictHostKeyChecking=yes "$DEPLOY_USER@$DEPLOY_HOST"
Some notes:
enable-openid-connect: trueis set on the job. Only this job gets the two environment variablesACTIONS_ID_TOKEN_REQUEST_URLandACTIONS_ID_TOKEN_REQUEST_TOKEN. The test and build jobs do not.::add-mask::hides the JWT and the Bao token in the job log, in case a later command prints them.- The private key exists only in the job’s temporary directory. The
trapremoves it. - The job uses
curlandjqand needs nobaoCLI. The usual runner images have both. - The pinned host key in the workflow is gone. After a reinstall of the web host, Ansible signs the new host key, and the workflow does not change.
The job log shows the certificate:
Key ID: "jwt-alice/blog-deploy-websites"
Valid: from 2026-11-15T16:51:02 to 2026-11-15T16:56:32
And the web host logs the deploy:
sshd[51234]: Accepted publickey for svc from 10.99.0.11 port 40122 ssh2: ED25519-CERT SHA256:... ID jwt-alice/blog-deploy-websites (serial 7342...) CA ED25519 SHA256:...
Test what must fail
- Push the same workflow to another branch. Bao answers the login with an error about the bound claims, and the job fails at step 2.
- Open a pull request. Here the deploy job does not run at all (
if: github.ref =‘refs/heads/main’). If somebody removes that line, Bao still refuses the =pull_requestsubject. - Try a shell with a deploy certificate. The host runs
podman auto-updateand closes the connection. - Try the certificate after six minutes. It has expired, and the host refuses it.
- Try the old deploy key. It must be refused: remove it from the host’s
authorized_keysand from Forgejo’s secrets.
For the branch test I pushed the workflow to a temporary branch oidc-test, watched the job fail with the bound-claims error, and deleted the branch.
Add a new site
- Add its
subto thewebsitesrole in the configuration script and run the script. - Copy the deploy job into the new repository.
There is no secret to create and no key to distribute.
Next, and last: Removing the plain SSH keys.
Further reading
- Forgejo Actions: OpenID Connect:
enable-openid-connectand the token request. - Forgejo Actions reference: workflow syntax, contexts and variables.
- About security hardening with OpenID Connect (GitHub): the same idea on GitHub, with a good explanation of the claims.
- OpenBao JWT/OIDC auth method:
bound_claims,bound_audiencesanduser_claim. - OpenBao SSH secrets engine API:
default_critical_optionsand the TTLs of a role. - sshd(8), authorized_keys format:
restrictandcommand=, which also work in a principals file.