Lucas WintherandClaude Opus 5
e1f152ec3e
README for humans, AGENTS.md for agents and contributors, and the docs that outlive any one platform: architecture, secrets, connectivity, triggering a deploy from another repository. CLAUDE.md, GEMINI.md and .claude/skills/ are pointers rather than copies, so every agent and every human reads the same text. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
2.5 KiB
Contributing
Running the checks
One command, and it is the same one CI runs:
make check # or: scripts/check.sh
It runs yamllint over the repository, installs the Galaxy collections, runs
ansible-lint at the production profile, and syntax-checks every playbook.
Locally it reaches for uv so this repository
needs no virtualenv of its own. If you already have the tools on PATH, use
RUNNER=installed scripts/check.sh to skip that.
The version pins live in scripts/check.sh and nowhere else; both CI
configurations ask the script for them, so a workflow cannot drift from what you
ran locally.
Lint and syntax-check are the definition of done for a playbook. They are static and safe.
What the checks will not catch
Nothing here talks to a host, so the gate cannot tell you that a deploy works.
Before proposing a change to a playbook, run it against your own host with
--check --diff and say in the pull request what it reported. If you cannot,
say that too — it is useful information, and better than an implied claim.
Conventions
They are in AGENTS.md, which is written for AI agents and is
equally the contributor guide. The short version:
- One playbook per stack, self-contained, tagged with the stack name.
- Reuse goes in the
compose_stackrole's variable contract, not in copy-pasted tasks or a second role. - Modules, not
shell. Fully-qualified collection names. Every task named. - A second run must report zero changes.
- No secrets in the repository — not in a
.env, and especially not inline in a compose file. Seedocs/secrets.md.
skills/adding-a-stack/SKILL.md is the
step-by-step version for the most common change.
Changing the examples
The six example stacks exist to demonstrate specific features of the role
contract — the table in server/README.md says which. If you
change one, check that whatever it was demonstrating is still demonstrated
somewhere, or the documentation that points at it stops being true.
New examples are welcome if they show something the current six do not. An example that shows the same thing a seventh way is a cost, not a contribution.
Reporting a security issue
Do not open a public issue for a vulnerability. Note that the example
credentials, hostnames and addresses in this repository are all fictional;
example.com is reserved by RFC 2606 and cannot resolve.