diff --git a/.ansible-lint b/.ansible-lint new file mode 100644 index 0000000..227804a --- /dev/null +++ b/.ansible-lint @@ -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/ diff --git a/.ansible-lint-ignore b/.ansible-lint-ignore new file mode 100644 index 0000000..0b9e1a4 --- /dev/null +++ b/.ansible-lint-ignore @@ -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] diff --git a/.gitea/playbooks-skip.txt b/.gitea/playbooks-skip.txt new file mode 100644 index 0000000..828940d --- /dev/null +++ b/.gitea/playbooks-skip.txt @@ -0,0 +1,14 @@ +# Playbooks that CI doesn't check (syntax check and ansible-lint), with why. +# One per line: . 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 diff --git a/.gitea/scripts/check-playbooks.sh b/.gitea/scripts/check-playbooks.sh new file mode 100644 index 0000000..f695ccb --- /dev/null +++ b/.gitea/scripts/check-playbooks.sh @@ -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 diff --git a/.gitea/workflows/playbooks.yaml b/.gitea/workflows/playbooks.yaml new file mode 100644 index 0000000..1c52a97 --- /dev/null +++ b/.gitea/workflows/playbooks.yaml @@ -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 diff --git a/docs/ci-cd/playbook-checks.md b/docs/ci-cd/playbook-checks.md new file mode 100644 index 0000000..aa68e5a --- /dev/null +++ b/docs/ci-cd/playbook-checks.md @@ -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.` 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.