Repository navigation
Document deploying from CI: GitHub Actions with an SSH key and the sops age key #89
Description
Problem
Found while setting up Abecra's staging on 2026-10-19. Every guide (docs/getting-started.md, docs/operator-guide.md, docs/secrets-guide.md) runs Cloudfall from an operator's machine: SOPS_AGE_KEY_FILE=~/.config/cloudfall/age.key, the operator's SSH agent, ansible-playbook on their PATH. Nothing says how to run artifact build and cloudfall deploy from a pipeline on merge to main, which is how most teams expect a staging environment to update.
The questions a team has to answer alone today:
- which secrets the runner needs (an SSH private key for the declared
ssh.user, the age key,known_hostsfor the server) and how to scope them (a GitHub environment per Cloudfall environment) - the toolchain to install (
uv,ansible-playbook>= 2.21.0,git>= 2.24.0,sops) and the versionsrequired_toolswill check - where artifacts and receipts go:
tmp/artifacts,tmp/deploymentsare on the runner and disappear with it, so the receipts that make deploys auditable are lost unless they are uploaded or committed - how an approval (
Application.spec.approval: manual) maps onto a CI job without an agent approving its own deploy - that
cloudfall deployneeds a release id fromartifact build, and thatartifact buildiscloudfall-engine, notcloudfall(or thebuild_artifactMCP tool)
Proposal
A docs/ci-deploy-guide.md with one worked GitHub Actions workflow, tested against a real project:
on: pushtomainin the fleet repository andworkflow_dispatchwith arefinput; app repositories trigger it withrepository_dispatch- secrets:
CLOUDFALL_SSH_KEY,CLOUDFALL_KNOWN_HOSTS,SOPS_AGE_KEYin a GitHub environment named after the Cloudfall environment, with required reviewers for production - steps: install the pinned toolchain,
secrets render,artifact build --ref,deploy --release --yes, uploadtmp/deploymentsas a workflow artifact (or commit receipts back, if the project wants them in git) - a note on the age key: one key per environment, so a staging runner cannot decrypt production secrets
If the guide shows that artifact build belongs in the cloudfall CLI (one tool for CI to install and pin), that is a follow-up issue.
Alternatives
- A Cloudfall-published reusable action: less copy-paste, but one more artifact to version; the guide comes first either way
Acceptance
- The guide's workflow, copied into a fresh project with the three secrets set, deploys a component on push and the run uploads its release and deployment receipts
- The guide shows that a runner holding only the staging age key cannot render production secrets
getting-started.mdlinks the guide
Activity
shipmill-romamo commentedon Oct 20, 2026
Triage: implement (documentation).
Confirmed on main (348ed73):
docs/getting-started.md,docs/operator-guide.mdanddocs/secrets-guide.mdall run Cloudfall from an operator's machine, and nothing covers a pipeline. Every question in the issue is answerable from the code today, so this is a guide, not a feature.The plan:
docs/ci-deploy-guide.mdwith one GitHub Actions workflow:pushtomainandworkflow_dispatchwith arefinput, a GitHub environment per Cloudfall environment holdingCLOUDFALL_SSH_KEY,CLOUDFALL_KNOWN_HOSTSandSOPS_AGE_KEY, required reviewers on productionrequired_toolschecks,secrets render,cloudfall-engine artifact build --ref,cloudfall deploy --release --yes, uploadtmp/artifactsandtmp/deploymentsas workflow artifacts so the receipts outlive the runnerapproval: manualmaps onto an environment's required reviewers, so no job approves its own deploygetting-started.mdThe guide is written from the code and checked against the CLI's real flags. A live run on a fresh project, which the issue's first acceptance point asks for, needs real secrets and a server; the guide will say it hasn't had one yet until someone runs it. Whether
artifact buildshould move intocloudfallstays a follow-up, as the issue says. I'll link the PR here.shipmill-romamo commentedon Oct 20, 2026
The guide is in #104:
docs/ci-deploy-guide.md, with one GitHub Actions workflow, a link fromgetting-started.md, and a row in the README's guide table. Every command and flag was checked against--helpand the source, and the guide says at the top that the workflow hasn't had a live run yet.Things the code showed that differ from this issue:
cloudfall deploywrites its receipt totmp/releases/<component>.json;tmp/deploymentsholds converge and domain receipts. The workflow uploadstmp/artifacts,tmp/releasesandtmp/env-receipts, and nevertmp/env, which holds decrypted valuesapproval: manualisn't enforced bydeployat all, so the guide makes the GitHub environment's required reviewers (with "prevent self-review") the gate. Filed separatelycloudfall initencrypts all ofsecrets/to one age key; the guide shows splitting.sops.yamlby environment, after which a staging runner fails withsecrets_decrypt_failedon a production file--refis a ref of the component's repository, so production rebuilds the same commit instead of reusing staging's archiveThis issue closes when #104 merges.
shipmill-romamo commentedon Oct 20, 2026
Released in v0.8.0rc1 (pre-release).
uv tool install --prerelease allow cloudfall==0.8.0rc1A plain install gets it with the next stable release.
If you filed this: react 👍 on this comment once it works for you, or reply if it doesn't.