Files
software-infrastructure/docs/ci-cd/playbook-checks.md
T
claudeandClaude Opus 5.5 b15bb337e9 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>
2026-11-15 09:25:00 -05:00

2.8 KiB

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:

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.