67 lines
3.1 KiB
Markdown
67 lines
3.1 KiB
Markdown
<!-- managed by the agents workflow -->
|
|
# AGENTS.md — how changes are made in this repo
|
|
|
|
This file is read by AI agents (via opencode) **and** by human developers. Follow it.
|
|
|
|
## What this repo is
|
|
A Docker Swarm homelab stack. `docker-compose.yml` is the stack; **merging to `main` deploys it to
|
|
node1 automatically** (GitOps). So every change that lands on `main` ships to production, one at a
|
|
time (deploys are serialized).
|
|
|
|
## Golden rules
|
|
- You may edit **any file** in this repo (including `ci/` and `.gitea/`).
|
|
- **NEVER push to `main`, and NEVER merge a pull request.** All work goes on a branch and becomes a
|
|
PR that a human reviews and merges. You do not have merge authority — do not attempt it.
|
|
- **Never print, exfiltrate, or invent secret values.** You may edit config that *references* secrets,
|
|
but never paste real secret values into comments, PRs, logs, or code.
|
|
- Keep changes **minimal** and match the conventions already in the file you're editing.
|
|
- Do the work on a **branch** — never paste code or diffs into the issue thread.
|
|
|
|
## Branches & pull requests
|
|
You start on branch `ai/issue-<N>` (N = the issue number).
|
|
|
|
**Split independent changes into separate PRs.** Infrastructure changes must be small and
|
|
independently mergeable, so they can be reviewed and deployed one at a time. For each independent
|
|
change, use its own branch:
|
|
|
|
```
|
|
git checkout main
|
|
git checkout -b ai/issue-<N>-<short-slug> # e.g. ai/issue-12-healthcheck, ai/issue-12-limits
|
|
# make just that one change
|
|
git add -A && git commit -m "<what changed>" && git push -u origin HEAD
|
|
```
|
|
|
|
- Only keep changes together on one branch if they genuinely must ship as a unit.
|
|
- Commit and **push incrementally** as you work, so progress is visible on the branch.
|
|
- **Do not open pull requests yourself** — the automation opens one PR per branch you push, and
|
|
the maintainer merges them sequentially.
|
|
|
|
## PR description
|
|
End your reply with a clean pull-request description wrapped EXACTLY between these markers.
|
|
Everything before `BEGIN_PR_DESCRIPTION` is treated as working notes and discarded:
|
|
|
|
```
|
|
BEGIN_PR_DESCRIPTION
|
|
## Summary
|
|
<1-2 sentences: what changed and why>
|
|
## Changes
|
|
<short bullet list of the changes>
|
|
END_PR_DESCRIPTION
|
|
```
|
|
|
|
Do not paste full files or large diffs — the review happens in the PR diff.
|
|
|
|
## Migrations (imperative changes)
|
|
`docker stack deploy` is **additive** — it will NOT remove a service, run a one-off command, prune,
|
|
or do anything imperative. For those, add a script under `migrations/` and the deploy runs it on the
|
|
swarm manager (after the stack deploy), exactly once, tracked in a ledger on the node.
|
|
|
|
- Name files `migrations/NNNN-short-description.sh` (zero-padded; applied in sorted order).
|
|
- Make them **idempotent** — guard with existence checks (the ledger can be lost on a node rebuild).
|
|
- Example: if you delete a service from `docker-compose.yml`, also add a migration that runs
|
|
`docker service rm homelab_<name>` — otherwise the old service keeps running after deploy.
|
|
|
|
## When unsure
|
|
If the task is genuinely unclear or missing details you cannot reasonably assume, make **no**
|
|
changes and reply with specific questions instead.
|