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
+15
View File
@@ -0,0 +1,15 @@
# ansible-lint settings for this repo's playbooks and vars.
# DevOps/software-infrastructure#51 (G3). CI: .gitea/workflows/playbooks.yaml.
#
# Roles are linted in their own repos (G5/G6), so roles/ is excluded here.
# Existing findings are listed in .ansible-lint-ignore, so the check passes
# today and fails on new problems. ansible-lint also applies yamllint's rules.
profile: production
offline: true
exclude_paths:
- roles/
- images/
- docs/
- .gitea/
- files/
- templates/
+113
View File
@@ -0,0 +1,113 @@
# Existing ansible-lint findings, baseline taken 2026-11-15 for
# DevOps/software-infrastructure#51 (G3). Fix entries and delete their lines;
# don't add lines to hide new findings.
ci-runner.yaml name[casing]
cluster.yaml fqcn[action-core]
cluster.yaml no-changed-when
counter-strike-2.yaml name[casing]
dex.yml yaml[line-length]
discourse_deploy.yaml yaml[indentation]
ejabberd.yaml yaml[empty-lines]
fediprofile.yaml yaml[empty-lines]
fictwiki.yaml name[casing]
group_vars/alpha.yaml yaml[trailing-spaces]
group_vars/beta.yaml yaml[trailing-spaces]
group_vars/gamma.yaml yaml[trailing-spaces]
group_vars/vms.yaml schema[vars]
group_vars/vms.yaml var-naming[no-reserved]
group_vars/vms.yaml yaml[truthy]
host_vars/alpha-control-plane.yaml schema[vars]
host_vars/alpha-control-plane.yaml var-naming[no-reserved]
host_vars/alpha-worker-0.yaml schema[vars]
host_vars/alpha-worker-0.yaml var-naming[no-reserved]
host_vars/alpha-worker-1.yaml schema[vars]
host_vars/alpha-worker-1.yaml var-naming[no-reserved]
host_vars/alpha-worker-10.yaml schema[vars]
host_vars/alpha-worker-10.yaml var-naming[no-reserved]
host_vars/alpha-worker-11.yaml schema[vars]
host_vars/alpha-worker-11.yaml var-naming[no-reserved]
host_vars/alpha-worker-12.yaml schema[vars]
host_vars/alpha-worker-12.yaml var-naming[no-reserved]
host_vars/alpha-worker-13.yaml schema[vars]
host_vars/alpha-worker-13.yaml var-naming[no-reserved]
host_vars/alpha-worker-14.yaml schema[vars]
host_vars/alpha-worker-14.yaml var-naming[no-reserved]
host_vars/alpha-worker-15.yaml schema[vars]
host_vars/alpha-worker-15.yaml var-naming[no-reserved]
host_vars/alpha-worker-16.yaml schema[vars]
host_vars/alpha-worker-16.yaml var-naming[no-reserved]
host_vars/alpha-worker-17.yaml schema[vars]
host_vars/alpha-worker-17.yaml var-naming[no-reserved]
host_vars/alpha-worker-2.yaml schema[vars]
host_vars/alpha-worker-2.yaml var-naming[no-reserved]
host_vars/alpha-worker-3.yaml schema[vars]
host_vars/alpha-worker-3.yaml var-naming[no-reserved]
host_vars/alpha-worker-4.yaml schema[vars]
host_vars/alpha-worker-4.yaml var-naming[no-reserved]
host_vars/alpha-worker-5.yaml schema[vars]
host_vars/alpha-worker-5.yaml var-naming[no-reserved]
host_vars/alpha-worker-6.yaml schema[vars]
host_vars/alpha-worker-6.yaml var-naming[no-reserved]
host_vars/alpha-worker-7.yaml schema[vars]
host_vars/alpha-worker-7.yaml var-naming[no-reserved]
host_vars/alpha-worker-8.yaml schema[vars]
host_vars/alpha-worker-8.yaml var-naming[no-reserved]
host_vars/alpha-worker-9.yaml schema[vars]
host_vars/alpha-worker-9.yaml var-naming[no-reserved]
host_vars/beta-control-plane.yaml schema[vars]
host_vars/beta-control-plane.yaml var-naming[no-reserved]
host_vars/beta-worker-0.yaml schema[vars]
host_vars/beta-worker-0.yaml var-naming[no-reserved]
host_vars/beta-worker-1.yaml schema[vars]
host_vars/beta-worker-1.yaml var-naming[no-reserved]
host_vars/beta-worker-2.yaml schema[vars]
host_vars/beta-worker-2.yaml var-naming[no-reserved]
host_vars/beta-worker-3.yaml schema[vars]
host_vars/beta-worker-3.yaml var-naming[no-reserved]
host_vars/evm.yaml schema[vars]
host_vars/evm.yaml var-naming[no-reserved]
host_vars/gamma-control-plane.yaml schema[vars]
host_vars/gamma-control-plane.yaml var-naming[no-reserved]
host_vars/network-file-system.yaml schema[vars]
host_vars/network-file-system.yaml var-naming[no-reserved]
host_vars/network-file-system.yaml yaml[brackets]
inspircd.yaml yaml[empty-lines]
jamulus.yaml var-naming[pattern]
kraken-bot.yaml yaml[trailing-spaces]
kubernetes.yaml fqcn[action-core]
kubernetes.yaml no-changed-when
luanti-s5.yaml yaml[trailing-spaces]
luanti.yaml yaml[trailing-spaces]
mediawiki.yaml yaml[empty-lines]
nvidia-device-plugin.yaml fqcn[action-core]
nvidia-device-plugin.yaml no-changed-when
open-archiver.yaml name[casing]
open-archiver.yaml yaml[empty-lines]
peertube.yaml name[casing]
poweredge-r350.yaml fqcn[action-core]
poweredge-r350.yaml no-changed-when
poweredge-r350.yaml risky-file-permissions
poweredge-r350.yaml yaml[line-length]
poweredge-r350.yaml yaml[trailing-spaces]
poweredge-r350.yaml yaml[truthy]
poweredge-r720.yaml fqcn[action-core]
poweredge-r720.yaml no-changed-when
poweredge-r720.yaml risky-file-permissions
poweredge-r720.yaml yaml[truthy]
qemu.yaml yaml[empty-lines]
reassign.yaml fqcn[action-core]
reassign.yaml no-changed-when
reassign.yaml risky-file-permissions
reassign.yaml yaml[empty-lines]
reassign.yaml yaml[trailing-spaces]
servers.yaml fqcn[action-core]
servers.yaml yaml[trailing-spaces]
shkeeper.yaml name[casing]
tes3mp.yaml var-naming[pattern]
vintage-story.yaml var-naming[pattern]
vintage-story.yaml yaml[line-length]
virtual-machine.yaml fqcn[action-core]
vms.yaml fqcn[action-core]
vms.yaml no-changed-when
workstations.yaml yaml[trailing-spaces]
www.yaml yaml[empty-lines]
+14
View File
@@ -0,0 +1,14 @@
# Playbooks that CI doesn't check (syntax check and ansible-lint), with why.
# One per line: <playbook> <reason>. Fix or delete a playbook, then remove its
# line here so CI covers it again. DevOps/software-infrastructure#51 (G3).
#
# Baseline taken 2026-11-15: all nine fail the syntax check today.
alpha-cluster.yaml role ericomeehan.gondwanamc is not a submodule here
bmcluster.yaml role ericomeehan.qemu-network is not a submodule here
cluster-host.yml unfinished: tasks with a name and no action
eom.dev.yaml role ericomeehan.qemu_network is not a submodule here
helm.yaml uses helm_repo, which no installed collection provides
jasmin.yaml role ericomeehan.jasmin is not a submodule here
lemmy.yaml role ericomeehan.lemmy is not a submodule here
libvirtGuests.yaml role ericomeehan.libvirtguest is not a submodule here
main.yaml role ericomeehan.libvirt_guests is not a submodule here
+92
View File
@@ -0,0 +1,92 @@
#!/bin/sh
# Check this repo's playbooks. DevOps/software-infrastructure#51 (G3).
# CI runs exactly this (.gitea/workflows/playbooks.yaml) in the ci-tools
# image; run it locally from the repo root the same way:
#
# sh .gitea/scripts/check-playbooks.sh # syntax, then lint
# sh .gitea/scripts/check-playbooks.sh syntax # ansible-playbook --syntax-check
# sh .gitea/scripts/check-playbooks.sh lint # ansible-lint (with yamllint rules)
# sh .gitea/scripts/check-playbooks.sh syntax gitea.yaml www.yaml
#
# Role submodules must be checked out first. They are all public:
# git -c url."https://gitea.eom.dev/".insteadOf="git@gitea.eom.dev:" \
# submodule update --init --jobs 4
#
# Playbooks load ../secrets.yaml (and a few vars/secrets.yaml). These checks
# don't evaluate variables, so an empty stub is enough. The repo is copied to
# a temporary directory and the stubs are written there, so this never reads,
# creates or overwrites a real secrets file.
#
# Playbooks in .gitea/playbooks-skip.txt are left out of both checks. Lint
# findings that already existed are in .ansible-lint-ignore. Regenerate that
# baseline only to drop fixed entries, never to hide a new finding.
set -eu
mode="${1:-all}"
[ "$#" -gt 0 ] && shift
repo="$(cd "$(dirname "$0")/../.." && pwd)"
skip_file="$repo/.gitea/playbooks-skip.txt"
export NO_COLOR=1 ANSIBLE_NOCOLOR=1 ANSIBLE_FORCE_COLOR=0
work="$(mktemp -d)"
trap 'rm -rf "$work"' EXIT
mkdir "$work/repo"
(cd "$repo" && tar -c --exclude=./.git -f - .) | tar -x -C "$work/repo"
printf '%s\n' '# Empty stub for CI checks only.' '{}' > "$work/secrets.yaml"
for d in "$work/repo" "$work/repo/vars"; do
mkdir -p "$d"
[ -e "$d/secrets.yaml" ] || cp "$work/secrets.yaml" "$d/secrets.yaml"
done
cd "$work/repo"
skips="$(sed -e 's/#.*//' -e '/^[[:space:]]*$/d' "$skip_file" 2>/dev/null | awk '{print $1}')"
is_skipped() {
printf '%s\n' "$skips" | grep -q -x -F -- "$1"
}
run_syntax() {
if [ "$#" -gt 0 ]; then
playbooks="$*"
else
# Every top-level playbook: a YAML file with a play-level hosts: key.
playbooks="$(grep -l -E '^[[:space:]-]*hosts:' -- *.yaml *.yml 2>/dev/null | sort)"
fi
failed=""
checked=0
for pb in $playbooks; do
if is_skipped "$pb"; then
echo "skip $pb (see .gitea/playbooks-skip.txt)"
continue
fi
checked=$((checked + 1))
if out="$(ansible-playbook --syntax-check -i localhost, "$pb" 2>&1)"; then
echo "ok $pb"
else
echo "FAIL $pb"
printf '%s\n' "$out" | sed 's/^/ /'
failed="$failed $pb"
fi
done
echo "syntax: checked $checked playbook(s)"
if [ -n "$failed" ]; then
echo "syntax check failed:$failed" >&2
return 1
fi
}
run_lint() {
set --
for pb in $skips; do set -- "$@" --exclude "$pb"; done
echo "ansible-lint (baseline: .ansible-lint-ignore)"
ansible-lint --nocolor -f pep8 "$@"
}
case "$mode" in
syntax) run_syntax "$@" ;;
lint) run_lint ;;
all) status=0; run_syntax || status=1; run_lint || status=1; exit "$status" ;;
*) echo "usage: $0 [syntax|lint|all] [playbook...]" >&2; exit 2 ;;
esac
+49
View File
@@ -0,0 +1,49 @@
# Syntax-check and lint this repo's playbooks. DevOps/software-infrastructure#51 (G3).
# Docs: docs/ci-cd/playbook-checks.md.
#
# Manual-only for now: the shared runner is still being stabilised (S3-S8,
# #36-#41), and the ci-tools image isn't published yet (G1, #49). Once both
# are done, replace the trigger with:
#
# push:
# branches: [main]
# paths-ignore: ["docs/**", "images/**", "**.md"]
# pull_request:
# paths-ignore: ["docs/**", "images/**", "**.md"]
#
# No secrets are used. Playbooks get an empty secrets stub in a temporary
# copy of the repo (see .gitea/scripts/check-playbooks.sh).
name: playbooks
on:
workflow_dispatch:
concurrency:
group: playbooks-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
container:
image: gitea.eom.dev/devops/ci-tools:1.0.0
timeout-minutes: 20
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
- name: Check out role submodules (all public, over HTTPS)
run: |
git config --global --add safe.directory "$PWD"
git -c url."https://gitea.eom.dev/".insteadOf="git@gitea.eom.dev:" \
submodule update --init --jobs 4
- name: Syntax check
run: sh .gitea/scripts/check-playbooks.sh syntax
- name: ansible-lint (with yamllint rules)
if: ${{ !cancelled() }}
run: sh .gitea/scripts/check-playbooks.sh lint
+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.