From 1dab77645ec35910dcdc5f7961b7caa1580a62cd Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 18:49:25 -0500 Subject: [PATCH] G2: reusable lint workflows for Ansible roles, Helm charts and Dockerfiles Three workflow_call workflows that run in the shared CI tools image (G1): - reusable-ansible-role-lint: ansible-lint (which includes yamllint's rules) on a copy of the role named as the playbooks use it, with the repo name also resolvable for galaxy's skeleton tests/test.yml. role-name is a warning; .ansible-lint-ignore baselines are honoured. - reusable-helm-lint: helm lint, then helm template | kubeconform for Kubernetes 1.31.2, with optional extra values files. - reusable-dockerfile-lint: hadolint on every Dockerfile, threshold warning by default. docs/ci-cd/adding-ci.md has caller templates, inputs, the baseline command, and what was and wasn't tested. Tested locally by running each workflow's steps verbatim in a local build of the tools image: ansible-role-gitea fails as-is (48 findings), passes with a baseline and fails on a new bad task; helm-jamulus passes, a missing-value template and an invalid Service fail; the tools Dockerfile passes and an unpinned one fails. Not yet run on the runner, and cross-repo uses: is untested. No callers added, so no runs start. Refs DevOps/software-infrastructure#50 Co-Authored-By: Claude Opus 5.5 --- .../workflows/reusable-ansible-role-lint.yaml | 71 ++++++++ .../workflows/reusable-dockerfile-lint.yaml | 52 ++++++ .gitea/workflows/reusable-helm-lint.yaml | 72 ++++++++ docs/ci-cd/adding-ci.md | 159 ++++++++++++++++++ 4 files changed, 354 insertions(+) create mode 100644 .gitea/workflows/reusable-ansible-role-lint.yaml create mode 100644 .gitea/workflows/reusable-dockerfile-lint.yaml create mode 100644 .gitea/workflows/reusable-helm-lint.yaml create mode 100644 docs/ci-cd/adding-ci.md diff --git a/.gitea/workflows/reusable-ansible-role-lint.yaml b/.gitea/workflows/reusable-ansible-role-lint.yaml new file mode 100644 index 0000000..2b6f641 --- /dev/null +++ b/.gitea/workflows/reusable-ansible-role-lint.yaml @@ -0,0 +1,71 @@ +# Reusable lint for an Ansible role repo. DevOps/software-infrastructure#50 (G2). +# Usage: docs/ci-cd/adding-ci.md. +# +# Runs ansible-lint in the shared CI tools image (G1, #49), so nothing is +# installed at run time. ansible-lint also applies yamllint's rules (yaml[*]), +# so one baseline covers both. Repo files are honoured if present: +# .yamllint yamllint settings ansible-lint uses for yaml[*] +# .ansible-lint ansible-lint config +# .ansible-lint-ignore baseline of known issues, so the check passes today +# and fails on new problems. Generate it with +# `ansible-lint --generate-ignore`. + +name: reusable-ansible-role-lint + +on: + workflow_call: + inputs: + tools-image: + description: CI tools image, pinned by version. + type: string + default: gitea.eom.dev/devops/ci-tools:1.0.0 + role-name: + description: >- + Name the playbooks use for this role (e.g. ericomeehan.gitea). + Default: "ericomeehan." plus the repo name without "ansible-role-". + type: string + default: "" + ansible-lint-args: + description: Extra ansible-lint arguments, e.g. "--profile production". + type: string + default: "" + +permissions: + contents: read + +jobs: + lint: + runs-on: ubuntu-latest + timeout-minutes: 15 + container: + image: ${{ inputs.tools-image }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + + - name: ansible-lint + env: + ROLE_NAME: ${{ inputs.role-name }} + REPO: ${{ github.repository }} + EXTRA_ARGS: ${{ inputs.ansible-lint-args }} + run: | + set -euo pipefail + name="${ROLE_NAME:-ericomeehan.${REPO##*/ansible-role-}}" + # ansible-lint takes the role's name from its directory (symlinks are + # resolved), so lint a copy in a directory with the name the + # playbooks use. Role repos are small. + roles="${RUNNER_TEMP:-/tmp}/roles" + rm -rf "${roles:?}/$name" + mkdir -p "$roles/$name" + cp -a . "$roles/$name/" + # The galaxy skeleton's tests/test.yml names the role by its repo + # name, so make that resolve too (syntax-check can't be skipped). + repo_name="${REPO##*/}" + if [ "$repo_name" != "$name" ]; then ln -sfn "$roles/$name" "$roles/$repo_name"; fi + export ANSIBLE_ROLES_PATH="$roles" + cd "$roles/$name" + echo "Linting role as ${name} with $(ansible-lint --version | head -1)" + # role-name is a warning: the roles keep galaxy's skeleton meta and + # are named ericomeehan. by the playbooks, which galaxy's + # naming rule rejects. Everything else counts. + # shellcheck disable=SC2086 # EXTRA_ARGS is a list of flags + ansible-lint --nocolor -f pep8 --warn-list role-name $EXTRA_ARGS diff --git a/.gitea/workflows/reusable-dockerfile-lint.yaml b/.gitea/workflows/reusable-dockerfile-lint.yaml new file mode 100644 index 0000000..1e54d07 --- /dev/null +++ b/.gitea/workflows/reusable-dockerfile-lint.yaml @@ -0,0 +1,52 @@ +# Reusable Dockerfile lint (hadolint). DevOps/software-infrastructure#50 (G2). +# Usage: docs/ci-cd/adding-ci.md. A repo's .hadolint.yaml is honoured. + +name: reusable-dockerfile-lint + +on: + workflow_call: + inputs: + tools-image: + description: CI tools image, pinned by version. + type: string + default: gitea.eom.dev/devops/ci-tools:1.0.0 + dockerfiles: + description: "Space-separated Dockerfile paths. Default: every Dockerfile* and *.Dockerfile in the repo." + type: string + default: "" + failure-threshold: + description: Lowest hadolint severity that fails the job (error, warning, info, style). + type: string + default: warning + +permissions: + contents: read + +jobs: + lint: + runs-on: ubuntu-latest + timeout-minutes: 10 + container: + image: ${{ inputs.tools-image }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + + - name: hadolint + env: + DOCKERFILES: ${{ inputs.dockerfiles }} + THRESHOLD: ${{ inputs.failure-threshold }} + run: | + set -euo pipefail + files=() + if [ -n "$DOCKERFILES" ]; then + for f in $DOCKERFILES; do files+=("$f"); done + else + while IFS= read -r f; do files+=("$f"); done < <( + find . -path ./.git -prune -o -type f \( -name 'Dockerfile*' -o -name '*.Dockerfile' \) -print | sort) + fi + if [ "${#files[@]}" -eq 0 ]; then + echo "::error::No Dockerfiles found. Set the dockerfiles input." + exit 1 + fi + printf 'Linting %s\n' "${files[@]}" + hadolint --no-color --failure-threshold "$THRESHOLD" "${files[@]}" diff --git a/.gitea/workflows/reusable-helm-lint.yaml b/.gitea/workflows/reusable-helm-lint.yaml new file mode 100644 index 0000000..fa0b042 --- /dev/null +++ b/.gitea/workflows/reusable-helm-lint.yaml @@ -0,0 +1,72 @@ +# Reusable lint and render check for a Helm chart. DevOps/software-infrastructure#50 (G2). +# Usage: docs/ci-cd/adding-ci.md. +# +# helm lint, then helm template | kubeconform against the cluster's Kubernetes +# version, in the shared CI tools image (G1, #49). + +name: reusable-helm-lint + +on: + workflow_call: + inputs: + tools-image: + description: CI tools image, pinned by version. + type: string + default: gitea.eom.dev/devops/ci-tools:1.0.0 + chart-path: + description: Path to the chart directory (the one with Chart.yaml). + type: string + default: "." + kube-version: + description: Kubernetes version to render and validate for. Keep it at the cluster's. + type: string + default: "1.31.2" + values-files: + description: Space-separated values files, relative to the chart, rendered in addition to the defaults. + type: string + default: "" + strict: + description: Run helm lint with --strict (warnings fail). + type: boolean + default: false + +permissions: + contents: read + +jobs: + lint: + runs-on: ubuntu-latest + timeout-minutes: 15 + container: + image: ${{ inputs.tools-image }} + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0 + + - name: helm lint and kubeconform + env: + CHART: ${{ inputs.chart-path }} + KUBE_VERSION: ${{ inputs.kube-version }} + VALUES_FILES: ${{ inputs.values-files }} + STRICT: ${{ inputs.strict }} + run: | + set -euo pipefail + cd "$CHART" + if grep -q '^dependencies:' Chart.yaml; then + helm dependency build --skip-refresh . || helm dependency build . + fi + + lint=(helm lint . --kube-version "$KUBE_VERSION") + if [ "$STRICT" = "true" ]; then lint+=(--strict); fi + "${lint[@]}" + + sets=("") + for f in $VALUES_FILES; do sets+=("$f"); done + for f in "${sets[@]}"; do + extra=() + label="default values" + if [ -n "$f" ]; then extra=(-f "$f"); label="$f"; fi + echo "== render and validate: ${label}" + helm template ci-render . --kube-version "$KUBE_VERSION" "${extra[@]}" \ + | kubeconform -strict -summary -ignore-missing-schemas \ + -kubernetes-version "${KUBE_VERSION#v}" - + done diff --git a/docs/ci-cd/adding-ci.md b/docs/ci-cd/adding-ci.md new file mode 100644 index 0000000..b70f32d --- /dev/null +++ b/docs/ci-cd/adding-ci.md @@ -0,0 +1,159 @@ +# Adding CI to a repo (G2) + +Refs: DevOps/software-infrastructure#50. + +Reusable workflows live in this repo under `.gitea/workflows/reusable-*.yaml`. +A repo adds a small caller file that points at one of them. Every lint job runs +in the shared CI tools image (`gitea.eom.dev/devops/ci-tools`, G1 #49), so +nothing is installed at run time and versions are the same everywhere. + +> **Status (2026-11-14):** written and tested locally, not yet run on the +> runner. The tools image isn't published yet (G1), and the runner is still +> being stabilised (S8 #41). Don't add callers to repos until both are done. +> G5 (#53) and G6 (#54) do the rollout. + +## The workflows + +| Workflow | For | Runs | +|---|---|---| +| `reusable-ansible-role-lint.yaml` | `ansible-role-*` repos | `ansible-lint`, which also applies yamllint's rules | +| `reusable-helm-lint.yaml` | Helm chart repos | `helm lint`, then `helm template` piped to `kubeconform` | +| `reusable-dockerfile-lint.yaml` | Repos with a Dockerfile | `hadolint` | +| `reusable-secret-scan.yaml` | Every repo | `gitleaks`, see [secret-scanning.md](secret-scanning.md) | + +## Caller templates + +Put one file per check in the repo's `.gitea/workflows/`. Pin the reusable +workflow to `@main` for now. Once these have releases (P8), pin a tag. + +Every caller should have a `concurrency` group and, where it helps, path +filters, so a burst of pushes doesn't queue many runs on the shared runner. + +### Ansible role + +```yaml +name: lint +on: + push: + branches: [main] + pull_request: +concurrency: + group: lint-${{ github.ref }} + cancel-in-progress: true +jobs: + ansible: + uses: DevOps/software-infrastructure/.gitea/workflows/reusable-ansible-role-lint.yaml@main +``` + +| Input | Default | Notes | +|---|---|---| +| `tools-image` | `gitea.eom.dev/devops/ci-tools:1.0.0` | | +| `role-name` | `ericomeehan.` + repo name without `ansible-role-` | The name the playbooks use, e.g. `ericomeehan.gitea`. | +| `ansible-lint-args` | empty | Extra flags, e.g. `--profile production`. | + +How it works and why: +- ansible-lint reads a role's name from its directory, so the job lints a copy + named like the playbooks name it. The repo's own name also resolves, because + galaxy's skeleton `tests/test.yml` uses it and `syntax-check` can't be + skipped. +- `role-name` is a warning, not a failure. Our roles keep galaxy's skeleton + `meta/main.yml` and are called `ericomeehan.`, which galaxy's naming + rule rejects. +- The repo's `.ansible-lint`, `.yamllint` and `.ansible-lint-ignore` are used + if present. + +**Baseline for existing problems.** Most roles have many existing findings +(ansible-role-gitea has 48, mostly `name[casing]` and `fqcn`). To pass today +and fail only on new problems, commit a baseline: + +```bash +docker run --rm -v "$PWD:/src" -w /tmp gitea.eom.dev/devops/ci-tools:1.0.0 bash -c ' + mkdir -p /tmp/roles && cp -a /src /tmp/roles/ericomeehan.NAME && + ln -s /tmp/roles/ericomeehan.NAME /tmp/roles/ansible-role-NAME && + cd /tmp/roles/ericomeehan.NAME && + ANSIBLE_ROLES_PATH=/tmp/roles ansible-lint --warn-list role-name --generate-ignore; + cp .ansible-lint-ignore /src/' +``` + +Replace `NAME`. Baselined findings still print, as warnings. Fixing them later +means deleting lines from `.ansible-lint-ignore`. + +### Helm chart + +```yaml +name: lint +on: + push: + branches: [main] + pull_request: +concurrency: + group: lint-${{ github.ref }} + cancel-in-progress: true +jobs: + helm: + uses: DevOps/software-infrastructure/.gitea/workflows/reusable-helm-lint.yaml@main + with: + chart-path: . +``` + +| Input | Default | Notes | +|---|---|---| +| `tools-image` | `gitea.eom.dev/devops/ci-tools:1.0.0` | | +| `chart-path` | `.` | Directory with `Chart.yaml`. | +| `kube-version` | `1.31.2` | The cluster's version on 2026-11-14. Bump it when the cluster is upgraded. | +| `values-files` | empty | Extra values files to render as well, space-separated. The defaults are always rendered. | +| `strict` | `false` | `helm lint --strict`. | + +Chart dependencies are built if `Chart.yaml` has any. kubeconform skips kinds +it has no schema for (CRDs) rather than failing on them. Schemas are fetched +from GitHub at run time. + +### Dockerfile + +```yaml +name: lint +on: + push: + branches: [main] + paths: ["**/Dockerfile*", "**/*.Dockerfile", ".hadolint.yaml"] + pull_request: + paths: ["**/Dockerfile*", "**/*.Dockerfile", ".hadolint.yaml"] +concurrency: + group: dockerfile-lint-${{ github.ref }} + cancel-in-progress: true +jobs: + hadolint: + uses: DevOps/software-infrastructure/.gitea/workflows/reusable-dockerfile-lint.yaml@main +``` + +| Input | Default | Notes | +|---|---|---| +| `tools-image` | `gitea.eom.dev/devops/ci-tools:1.0.0` | | +| `dockerfiles` | every `Dockerfile*` and `*.Dockerfile` | Space-separated paths. The job fails if it finds none. | +| `failure-threshold` | `warning` | `error`, `warning`, `info` or `style`. Use a `.hadolint.yaml` for per-rule ignores. | + +## How these were tested (2026-11-14) + +Each workflow's `run:` steps were taken from the YAML as written and run inside +a local build of the tools image (1.0.0), against: + +| Workflow | Case | Result | +|---|---|---| +| ansible-role-lint | DevOps/ansible-role-gitea as it is | fails, 48 findings | +| | the same with a generated baseline | passes | +| | baseline plus a new `shell:` task | fails on the new task only | +| helm-lint | DevOps/helm-jamulus | passes | +| | a template referencing a missing value | fails in `helm lint` | +| | a Service with a string port | fails in kubeconform | +| dockerfile-lint | `images/ci-tools/Dockerfile` | passes | +| | `FROM debian:latest` with unpinned apt | fails (DL3007, DL3008) | +| | repo with no Dockerfile | fails with a clear message | + +`actionlint` 1.7.12 and `yamllint` pass on all the workflow files. + +**Not tested yet:** +- Running on the Gitea runner at all, including `container.image` from an input. +- Calling a workflow from another repo with `uses: owner/repo/path@ref`, and + from a private repo calling this public one. This is the G2 acceptance check. + If the runner can't resolve cross-repo `uses:`, the fallback is to copy the + caller with the steps inlined, generated from these files.