G3: syntax-check and lint this repo's playbooks in CI

.gitea/scripts/check-playbooks.sh runs ansible-playbook --syntax-check on
every top-level playbook and ansible-lint (production profile, with
yamllint's rules) on the repo's own files, in a temporary copy with empty
secrets stubs, so it never touches a real secrets file. Roles are excluded;
they're linted in their own repos.

Baselines so the check passes today and fails on new problems:
- .gitea/playbooks-skip.txt: nine playbooks that fail the syntax check now
  (missing roles, an unknown module, an unfinished playbook), with reasons.
- .ansible-lint-ignore: 110 existing file/rule findings.

The workflow (.gitea/workflows/playbooks.yaml) is manual-only until S8 passes
and the ci-tools image is published; its header has the push/pull_request
trigger. Docs: docs/ci-cd/playbook-checks.md.

Refs DevOps/software-infrastructure#51

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-15 09:25:00 -05:00
co-authored by Claude Opus 5.5
parent 1dab77645e
commit b15bb337e9
6 changed files with 344 additions and 0 deletions
+61
View File
@@ -0,0 +1,61 @@
# Playbook checks
CI for this repo's own playbooks and vars: `ansible-playbook --syntax-check`
on every top-level playbook, then `ansible-lint`, which also applies
yamllint's rules. Roles are linted in their own repos (G5 and G6), so `roles/`
is excluded from lint. Tracked in DevOps/software-infrastructure#51 (G3).
| File | Purpose |
|---|---|
| `.gitea/workflows/playbooks.yaml` | The workflow. Manual-only until S8 (#41) passes and the ci-tools image (#49) is published. |
| `.gitea/scripts/check-playbooks.sh` | What CI runs. Run it locally the same way. |
| `.gitea/playbooks-skip.txt` | Playbooks left out of both checks, each with a reason. |
| `.ansible-lint` | Lint profile (`production`) and excluded paths. |
| `.ansible-lint-ignore` | Baseline of findings that existed on 2026-11-15. |
## Run it locally
From the repo root, with Docker, in the same image CI uses:
```bash
git -c url."https://gitea.eom.dev/".insteadOf="git@gitea.eom.dev:" submodule update --init --jobs 4
docker run --rm -v "$PWD":/repo:ro -w /repo gitea.eom.dev/devops/ci-tools:1.0.0 sh .gitea/scripts/check-playbooks.sh
```
`syntax` or `lint` runs one check. `syntax gitea.yaml www.yaml` checks only
those playbooks. Without Docker, run the script with ansible-core 2.21 and
ansible-lint 26 installed.
## Secrets
Playbooks load `../secrets.yaml`, and a few load `vars/secrets.yaml` or
`secrets.yaml`. The checks don't evaluate variables, so the script copies the
repo to a temporary directory and writes empty stubs there. It never reads,
creates or overwrites a real secrets file, and CI uses no secrets.
## When it fails
- **Syntax check:** the log shows Ansible's error for each failing playbook.
A missing role usually means a new `roles/ericomeehan.<name>` wasn't added
as a submodule.
- **ansible-lint:** fix the new finding. Don't add it to
`.ansible-lint-ignore`. If a rule is wrong for this repo, change
`.ansible-lint` in its own commit and say why.
## Shrinking the baselines
- Fixing a skipped playbook: fix it, or delete it if it's dead, then remove
its line from `.gitea/playbooks-skip.txt`. CI then checks it again.
- Fixing lint findings: fix them, then delete their lines from
`.ansible-lint-ignore`. To see what's left, regenerate the file in a scratch
copy with `ansible-lint --generate-ignore` and compare. Commit only removals.
## Baseline on 2026-11-15
- 60 of 69 playbooks pass the syntax check. The other nine are in the skip
list: seven use roles that aren't submodules here, `helm.yaml` uses a
`helm_repo` module that no installed collection provides, and
`cluster-host.yml` has tasks with no action.
- `.ansible-lint-ignore` lists 110 file and rule pairs. The most common are
`fqcn[action-core]`, `var-naming`, `schema[vars]` and yamllint's
indentation and whitespace rules.