Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 42 additions & 0 deletions .github/workflows/validate-catalog.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
name: Validate Compose catalog

on:
pull_request:
paths:
- "**/docker-compose.y*ml"
- "**/compose.y*ml"
- "catalog-validation.yaml"
- "services.yaml"
- "README.md"
- "_scripts/validate_catalog.py"
- "*.sh"
- "tests/**"
- ".github/workflows/validate-catalog.yml"
workflow_dispatch:

permissions:
contents: read

jobs:
validate:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4

- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: "3.x"

- name: Install YAML parser
run: python -m pip install --disable-pip-version-check --no-input pyyaml

# This is the same non-deploying command documented for local use. It
# only runs `docker compose config --quiet`; it never pulls, starts, or
# rewrites a service.
- name: Validate catalog and maintenance scripts
run: python3 _scripts/validate_catalog.py

- name: Run focused parser fixtures
run: python3 -m unittest discover -s tests -p 'test_*.py'
50 changes: 49 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,55 @@ Many services default to the same host ports (e.g. `8080`). The included `check-
./check-ports.sh --fix
```

# Roadmap
# Catalog Validation

Catalog-changing pull requests use the same non-deploying validation command
locally and in GitHub Actions:

The command requires Python 3, Docker Compose, and PyYAML. Install it with
`python3 -m pip install pyyaml`.

```bash
python3 _scripts/validate_catalog.py
```

The canonical inventory is [catalog-validation.yaml](catalog-validation.yaml).
It enumerates all 64 maintained Compose examples, keeps archived examples
under `archive/` and generated output under `docs/` out of the active set, and
requires a manifest update when a new Compose file is added. The validator:

- runs `docker compose config --quiet` for every active entry;
- copies each file to a temporary directory and creates sanitized example
`env_file` values, so local `.env` files and secrets are never read;
- reports every path, including the two documented template exceptions;
- runs non-mutating `bash -n` checks for each maintained shell script; and
- validates the `services.yaml` updater registry and README Compose links.

It never pulls images, builds images, starts containers, deploys services,
rewrites catalog files, or contacts private infrastructure. The two expected
template exceptions are intentionally enumerated in the manifest: Actual
Budget's comment-only environment block and Calibre-Web's
`<path_to_books>` placeholder are not valid until a user customizes the sample.
Immich, Linkding, Nextcloud, Prometheus, Tandoor, and Windmill are checked with
temporary sanitized environment defaults rather than any local environment
files.
The standalone `lidarr/` example is likewise documented as an intentionally
unlisted README row because the combined `media-server` stack is the advertised
catalog entry.

The separate scheduled updater can still be blocked at its pull-request step
by the repository's GitHub Actions permission setting (`GitHub Actions is not
permitted to create or approve pull requests`). The validation gate is
read-only and does not change that external setting.

# Planning

Committed implementation work is tracked in the
[Server Compose Linear project](https://linear.app/carteakey/project/server-compose-7a4e19322863).
The roadmap below is for ideas and possible future directions; do not duplicate
committed Linear issues in it or in GitHub Issues.

# Roadmap

- List will continue to grow, but will try to not be overwhelming.
- Individual README files for each compose.
Expand Down
Loading
Loading