README.md

devops

Shared CI/CD infrastructure for Knight Owl repositories.

Why This Repo Exists

Third-party GitHub Actions for linting (setup-shfmt, hadolint-action, etc.) introduce an unnecessary trust surface — each is a dependency maintained by someone outside the org that runs in CI with repo-level permissions. This repo replaces all of them with a single org-maintained Docker image. CI jobs run make lint inside the image, executing the exact same commands developers run locally. See Supply-Chain Security for the full rationale and guidelines.

ci-tools Image

A Docker image containing linting and formatting tools used across Knight Owl CI pipelines. Published to GHCR at ghcr.io/knight-owl-dev/ci-tools.

Tools

Tool	Purpose
actionlint	GitHub Actions workflow linting
bats	Shell script test framework with bats-support, bats-assert, bats-file helper libraries
busted	Lua testing framework
biome	JavaScript/TypeScript linting
chktex	LaTeX document linting
git	Version control (build-time cloning and runtime use)
gpg	GPG signature verification
hadolint	Dockerfile linting
luacheck	Lua script linting
make	Build automation
parallel	Parallel execution backend for bats --jobs
markdownlint-cli2	Markdown linting
npm	Package manager (upgraded beyond base image for CVE fixes)
rsync	File synchronization for build assembly
shellcheck	Shell script linting
shfmt	Shell script formatting
stylelint	CSS linting
validate-action-pins	GitHub Actions SHA pin verification

Pinned versions and checksums are tracked in images/ci-tools/versions.lock.

Usage

Reference the image in a GitHub Actions workflow:

jobs:
  lint:
    runs-on: ubuntu-latest
    container: ghcr.io/knight-owl-dev/ci-tools:latest
    steps:
      - uses: actions/checkout@v6
      - run: make lint

Caveat: Pass .github/workflows/*.yml explicitly to actionlint instead of relying on auto-discovery. Auto-discovery breaks inside CI containers where the workspace path doesn't match what actionlint expects.

actionlint .github/workflows/*.yml

Publishing

The image is published automatically when a version tag is pushed. The publish workflow builds and pushes the image, packages org-developed local tools into platform archives and .deb packages, creates a GitHub Release with checksums, and notifies downstream apt and homebrew-tap repos.

git tag v1.0.0
git push origin v1.0.0

See Publish an Image for the full pipeline.

Local Development

make sync      # Resolve, build, and verify (IMAGE=ci-tools by default)
make resolve   # Resolve all tools to latest versions
make resolve TOOLS="shfmt:v3.11.0"  # Pin specific tool versions
make build     # Build image locally via Docker Compose
make verify    # Verify all tools are present in the image
make lint      # Lint this repo's files
make man       # Preview man pages
make help      # Show all available commands

Note: make resolve and make sync write images/<IMAGE>/versions.lock. Commit the updated lockfile after resolving.

How-To Guides

• Sync an Image
• Add an Image
• Publish an Image

Acknowledgments

This project relies on excellent open source tools maintained by their respective communities:

• ShellCheck by Vidar Holen (GPLv3)
• shfmt by Daniel Martí (BSD-3-Clause)
• actionlint by rhysd (MIT)
• hadolint by Hadolint contributors (GPLv3)
• markdownlint-cli2 by David Anson (MIT)
• Biome by Biome contributors (MIT/Apache-2.0)
• busted by Lunar Modules (MIT)
• luacheck by Lunar Modules (MIT)
• stylelint by stylelint contributors (MIT)
• ChkTeX by ChkTeX contributors (GPLv2+)
• bats-core by bats-core contributors (MIT)
• GNU Parallel by Ole Tange (GPLv3+)

License

MIT