[shipmill-romamo]

Summary

Adds docs/ci-deploy-guide.md: one GitHub Actions workflow that deploys a component from CI (push to main, workflow_dispatch with environment/component/ref inputs, and repository_dispatch from an app repo). It installs the toolchain, loads CLOUDFALL_SSH_KEY, CLOUDFALL_KNOWN_HOSTS and SOPS_AGE_KEY from a GitHub environment named after the Cloudfall environment, runs cloudfall doctor, config validate, secrets render, cloudfall-engine artifact build --ref, cloudfall deploy (plan, then --yes --env-file), and uploads the receipts. Linked from docs/getting-started.md and the README's guide table. A changelog fragment is included.

The guide follows the code where it differs from the issue's assumptions:

• Receipts. cloudfall deploy writes its receipt to tmp/releases/<component>.json, not tmp/deployments (that directory holds converge/domain receipts). The upload covers tmp/artifacts/**/*.json, tmp/releases/ and tmp/env-receipts/, and never tmp/env/
• Approval. Application.spec.approval is validated and written into the inventory, but no command reads it. deploy --yes treats manual and automatic the same. The guide says so, and makes GitHub required reviewers with "Prevent self-review" the gate
• Age keys. cloudfall init writes one .sops.yaml rule for all of secrets/, so per-environment keys need the project to split the rule by secrets/<environment>/. The guide shows the split and sops updatekeys. Cloudfall decrypts only the files a component's references name, so a staging runner fails with secrets_decrypt_failed on a production fragment. Cloudfall doesn't check that references match the servers' environment, and the guide says that too
• SSH keys. These are already scoped. The inventory gives a server only the active keys of its own environment, so a CI key declared with --environment staging reaches staging servers only
• --ref is a ref of the component's repository, not the project repo. The release id is at data.release of the build's JSON answer

The guide says near the top that the workflow has not had a live run yet.

What was checked

• Every command and flag against uv run cloudfall ... --help / uv run cloudfall-engine ... --help (0.7.0) and the source: deploy, secrets render, artifact build (--output-schema for release), add ssh-key --environment, playbook run, playbook list, doctor
• Tool minimums from required_tools: ansible-playbook 2.21.0, git 2.24.0 (sdk/src/cloudfall/app.py, engine/src/cloudfall_engine/{playbook,artifact}.py), sops 3.8.0 (secrets render). cloudfall doctor was run locally and reports all three
• The guide's YAML blocks parse
• uv run ruff check ., uv run mypy, uv run pytest (526 passed)

Not verified: a live run on GitHub against a real server. That covers the ssh-agent across steps, the sops checksum file's entry name for linux.amd64, and the receipts upload.

Fixes #89

🤖 Generated with Claude Code