blackoutsecure/Blackout Secure Nginx Config Validator

Pre-merge `nginx -t` validation for in-repo nginx config trees, with `envsubst` template rendering.

Trust Signals

Scorecard Score: not yet scored
Maintenance Recency: Activelast commit May 24, 2026
License: Apache 2.0

Pinned Snippet

workflow.ymlSHA-pinned

uses: blackoutsecure/bos-nginx-config-validator@a58e5a54581de8605f682b29c9bf7641bea82aa9 # no releases — HEAD as of 2026-07-11

tags can be moved; commit SHAs can't. why a SHA?

Inputs

name	description	required	default
config_path	Repo-relative path to your `nginx.conf` (no leading `./`). Mounted read-only into the validation container at `/etc/nginx/nginx.conf`. Defaults to a common docker-image-style layout (`root/etc/nginx/nginx.conf`).	no	root/etc/nginx/nginx.conf
templates_path	Repo-relative path to a directory containing `*.conf.template` files (no leading `./`). Each `<name>.conf.template` is rendered via `envsubst` into `<templates_target_dir>/<name>.conf` inside the validation container. Missing or empty directories are tolerated — only `nginx.conf` is validated in that case. Set to an empty string to disable template rendering entirely.	no	root/etc/nginx/http.d
template_vars	Newline-separated `KEY=VALUE` pairs forwarded to `envsubst` when rendering templates. Only the listed keys are substituted (we pass a positional `${KEY}` list to `envsubst`), so unrelated `${...}` strings — for example nginx's own `$remote_addr`, `$status` — pass through unchanged. Keys must match `[A-Za-z_][A-Za-z0-9_]*`; values must not contain newlines.	no	""
templates_target_dir	Absolute path inside the validation container where rendered templates land. Must match the `include` directive in your `nginx.conf`. The default works for the `include /run/nginx/http.d/*.conf;` convention.	no	/run/nginx/http.d
nginx_image	Container image used for validation. Defaults to the LinuxServer.io nginx image (matches the runtime of the BOS docker-* repos). Any OCI-compatible image works as long as it ships `nginx` on `PATH`; `envsubst` is auto-installed via the image's package manager (apk / apt / dnf / yum) when templates are in use and gettext is missing. Pin to a specific tag so Dependabot's `docker` ecosystem can bump it.	no	lscr.io/linuxserver/nginx:latest
auto_fill_unknown_vars	Fallback value substituted for any `${UPPERCASE_VAR}` reference found in your `.conf.template` files but not* declared in `template_vars`. The default `127.0.0.1` makes most templates validate out-of-the-box because the common unmet reference is a literal hostname in `proxy_pass http://${UPSTREAM_HOST}:8000;` — and `nginx -t` resolves literal upstream hostnames at config-load time, so an unresolvable name (or an empty expansion) fails the check. Auto-fills are logged with a `WARNING` and a list of the affected keys so you know to add them to `template_vars`. Set to an empty string (`auto_fill_unknown_vars: ''`) for strict mode where undeclared `${UPPERCASE_VAR}` tokens pass through to nginx untouched and surface as parse errors. The heuristic targets uppercase names only, so nginx-native variables like `${remote_addr}` and `${host}` are never matched.	no	127.0.0.1

Outputs

name	description
validated	`true` when `nginx -t` exits 0; otherwise the step fails before this is written.