Linux Lunatix

CI deploys without a deploy key

Stefan Marx
| 7 minutes

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:

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:

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

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

  1. Add its sub to the websites role in the configuration script and run the script.
  2. 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

Previous: Hosts that trust the SSH CA Next: Removing the plain SSH keys

Related content

Why SSH certificates
Removing the plain SSH keys
Hosts that trust the SSH CA