| name | houndarr-ci |
| description | Houndarr's CI workflow reference and branch protection. Loads when reading or editing .github/workflows/. Covers the 11 required status checks (exact names matter for branch protection), the additional non-required workflows, the paths-ignore + ci-skip pattern that keeps docs-only PRs green, and the rule against changing required check job names. |
| paths | [".github/workflows/**"] |
Houndarr CI conventions
Required checks (11; branch protection enforced)
| Check name | Workflow file | What it runs |
|---|
| Lint (ruff) | quality.yml | ruff check . |
| Format (ruff) | quality.yml | ruff format --check . |
| Type check (mypy) | quality.yml | mypy src/ |
| Test (Python 3.13) | tests.yml | pytest -q --tb=short + compile check + --help |
| Dependency audit (pip-audit) | security.yml | pip-audit against requirements.txt + requirements-dev.txt generated on the fly via uv export --frozen from pyproject.toml + uv.lock |
| SAST (bandit) | security.yml | bandit -r src/ -c pyproject.toml |
| Trivy filesystem scan | security.yml | trivy fs . (CRITICAL/HIGH with known fix) |
| Dependency review | dependency-review.yml | PR dependency diff vs GitHub Advisory Database |
| Build (no push) | docker.yml | Multi-arch Docker build (amd64/arm64), no push |
| Trivy image scan | docker.yml | Trivy scan of built Docker image (CRITICAL/HIGH with known fix) |
| Security smoke test | security-smoke-test.yml | Live container: unauthenticated sweep, CSRF, XFF, rate limiting, API key exposure, container security |
The six main workflows (quality, tests, security, dependency-review,
docker, security-smoke-test) use
paths-ignore: ["docs/**", "**/*.md", "website/**", ".claude/**"]. When a PR
touches only those paths, ci-skip.yml provides passing no-op jobs with
identical check names so branch protection is satisfied.
Additional workflows (not required checks)
| Workflow | Trigger | Purpose |
|---|
version-check.yml | PRs changing VERSION or CHANGELOG.md | Validates VERSION format, CHANGELOG heading match, allowed ### headers, --- separator |
release.yml | v* tag push | Validates VERSION == tag, extracts CHANGELOG block, creates GitHub Release |
chart.yml | v* tag push | Packages charts/houndarr/ with version from VERSION file, pushes to oci://ghcr.io/av1155/charts |
dockerfile-lint.yml | Changes to Dockerfile | hadolint Dockerfile |
workflow-lint.yml | Changes to .github/workflows/** | actionlint via reviewdog |
api-snapshot-refresh.yml | Weekly (Monday 10:00 UTC) + manual | Fetches upstream Radarr/Sonarr/Whisparr/Lidarr/Readarr OpenAPI specs, updates docs/api/ snapshots and tests/test_docs_api.py hashes, opens a PR if changed |
pages.yml | Pushes to main touching website/** | Deploys docs site to GitHub Pages |
test-deploy.yml | PRs touching website/** | Tests Docusaurus build without deploying |
link-check.yml | PRs touching **/*.md, **/*.mdx, lychee.toml + weekly (Monday 08:00 UTC) + manual | Runs lychee against every Markdown file to catch broken external links; rules live in lychee.toml |
cleanup-actions-cache.yml | Daily (05:00 UTC) + manual | Prunes stale GitHub Actions caches |
Branch protection on main
- 11 required status checks (strict; branch must be up to date)
- PRs required, stale reviews dismissed, conversation resolution required
- Required approving reviews is 0, so no approval blocks a merge
- Linear history enforced (no merge commits)
- No force pushes, no branch deletions
- Admin enforcement is off. The rules above bind contributors; the
maintainer account can push to
main and merge past a failing check.
The hooks in .claude/settings.json are the real block on direct
edits and pushes while on main.
- CODEOWNERS assigns
@av1155 to every file, but code owner review is
not a required gate
Don't break this
- Do not modify the 11 required check job names; branch protection
depends on exact name matches.
- Do not change
ci-skip.yml job names without updating branch protection.
- Keep
paths-ignore patterns in sync across the six main workflows.
- If mypy CI fails with "merge ref not found": push an empty commit to
retrigger.
- Keep every action pinned to a full 40-character commit SHA with the
release version as the last token of a trailing comment
(
uses: owner/repo@<sha> # vX.Y.Z). Dependabot rewrites the SHA and
the comment together, but only while the version ends the comment.
A tag or branch ref can be repointed by the action owner; a SHA
cannot. When pinning by hand, dereference annotated tags to their
commit: for those actions git/ref/tags/vN returns a tag object
whose SHA the runner cannot resolve.
