From 9e7b51b69a8f6fe7abeca88ca71a7d6a302ca331 Mon Sep 17 00:00:00 2001
From: Jeremie Fraeys <jfaeys@gmail.com>
Date: Tue, 20 Jan 2026 17:10:41 -0500
Subject: [PATCH] docs: document Actions SSH key setup

- Document required register/deregister SSH keys for controller workflows\n- Update vault.example.yml with FORGEJO_API_TOKEN and SSH public key placeholders
---
 README.md                 | 30 +++++++++++++++++++++++++++++-
 secrets/vault.example.yml |  3 +++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index a04736a..7e43dcc 100644
--- a/README.md
+++ b/README.md
@@ -145,7 +145,7 @@ This is used to allowlist Loki (`services:3100`) to only the web host.
 A Forgejo runner is deployed on the `web` host (`roles/forgejo_runner`).
 
 - Requires `FORGEJO_RUNNER_REGISTRATION_TOKEN` in `secrets/vault.yml`.
-- Uses a single generic `docker` label by default.
+- Uses a single `self-hosted` label by default.
 - The role auto re-registers the runner if labels change.
 
 To force re-register (e.g. after deleting the runner in Forgejo UI):
@@ -158,6 +158,34 @@ ansible-playbook playbooks/app.yml \
   -e forgejo_runner_force_reregister=true
 ```
 
+## SSH from Actions to services
+
+If a workflow running on the `web` runner needs SSH access to the `services` host:
+
+The controller expects two separate SSH keys restricted to forced commands:
+
+- `infra-register-stdin` (register)
+- `infra-deregister` (deregister)
+
+Public keys (installed on the `services` host via Ansible/vault):
+
+- `SERVICE_SSH_REGISTER_PUBLIC_KEY`
+- `SERVICE_SSH_DEREGISTER_PUBLIC_KEY`
+
+Private keys (stored as Forgejo Actions secrets):
+
+- `SERVICE_SSH_KEY_REGISTER`
+- `SERVICE_SSH_KEY_DEREGISTER`
+
+To generate/update both Actions secrets (and optionally update both public keys in vault):
+
+```bash
+python3 scripts/forgejo_set_actions_secret.py \
+  --repo jfraeysd/infra-controller \
+  --generate-ssh-keys \
+  --update-vault-both-public-keys
+```
+
 ## Deploy
 
 Services:
diff --git a/secrets/vault.example.yml b/secrets/vault.example.yml
index 5a549ee..062ae4e 100644
--- a/secrets/vault.example.yml
+++ b/secrets/vault.example.yml
@@ -20,3 +20,6 @@ AUTHELIA_OIDC_PRIVATE_KEY_PEM:
 AUTHELIA_OIDC_GRAFANA_CLIENT_SECRET:
 AUTHELIA_OIDC_FORGEJO_CLIENT_SECRET:
 FORGEJO_RUNNER_REGISTRATION_TOKEN:
+FORGEJO_API_TOKEN:
+SERVICE_SSH_REGISTER_PUBLIC_KEY:
+SERVICE_SSH_DEREGISTER_PUBLIC_KEY: