| name | scripts-and-automation |
| description | caddy-security repository automation, Makefile target selection, local build/test/report/coverage commands, local go-authcrunch go.mod replacement shim workflow, asset and documentation update scripts, release/version workflows, generated artifact handling, and guardrails for dependency, devbuild, cleanup, and release actions. Use when choosing, running, documenting, or updating repository scripts and Make targets; troubleshooting CI/build/test automation; coordinating caddy-security development with local go-authcrunch changes; refreshing Caddyfile/config fixtures; deciding whether generated outputs belong in a change; or preparing releases for this Go/Caddy module. |
Scripts and Automation
Overview
Use the Makefile as the primary automation surface for this Go module. This
repository builds a Caddy command binary at bin/authcrunch from
cmd/authcrunch/main.go; the binary registers the security app, the
authenticate and authorize integrations, Caddy standard modules, and
caddy-trace.
Prefer narrow go test commands for quick validation while editing. Use the
Makefile targets when the user asks for the repository workflow, reports,
release preparation, fixture formatting, or CI-like behavior.
Command Selection
- Use
go test ./... for a fast all-package check without coverage reports.
- Use
go test -run <TestName> ./... for focused validation.
- Use
make build to compile cmd/authcrunch/main.go into bin/authcrunch,
print the binary version, and format assets/**/Caddyfile files.
- Use
make when the user asks for the default build; it runs info and
build.
- Use
make test for the full local workflow: create .coverage, install test
report tools if missing, run go test -json -v ./..., write
.coverage/test_output.jsonl, generate coverage and test-output reports, and
fail if any JSON test action failed. Review the resulting
.coverage/coverage.html and .coverage/test_output.html files in a browser
for easy coverage and test-output inspection.
- Use
make qtest only when the Makefile's current QUICK_TEST_PATTERN is the
desired scope. Prefer direct go test -run ... ./... instead of editing the
Makefile just to run a different quick test.
- Use
make run-reports only after .coverage/test_output.jsonl and
.coverage/coverage.out exist.
- Use
make coverage after a previous coverage run or make test; the target
reads .coverage/coverage.out before it refreshes coverage.
- Use
make fmtcfg to format Caddyfile fixtures under
testdata/caddyfile_adapt and assets/config; it requires an existing
bin/authcrunch.
- Use
make clean only when cleanup is requested; it removes generated
.coverage/ and bin/ directories.
If documentation mentions make ctest, treat it as stale in this repository and
choose make test, make qtest, or direct go test instead.
Tooling and Dependencies
The module declares Go 1.25.0 and Caddy v2.11.2.
make dep installs developer tools with go install, including golint,
xcaddy, versioned, and richgo.make install-test-tools installs richgo, tparse, and
go-test-report if they are missing.go mod tidy, go mod verify, go mod download, go install, and xcaddy
may require network access.
When a dependency or module command fails because of sandboxed network access,
rerun it with the normal escalation flow instead of replacing the repository
workflow with an ad hoc workaround.
Development Builds
make devbuild uses xcaddy to build Caddy into bin/authcrunch with this
module, caddy-security-secrets-static-secrets-manager, caddy-trace, and a
local go-authcrunch replacement. It writes to the sibling directory
../xcaddy-caddy-security, but the current Makefile hard-codes the
go-authcrunch replacement path in its --replace argument instead of using the
generic ../go-authcrunch path.
Run make devbuild only when the user explicitly wants that integrated local
Caddy build and the sibling output plus hard-coded go-authcrunch path are
acceptable for the current machine, or after updating the Makefile path
deliberately.
Local go-authcrunch Development
Development in caddy-security often connects this module to a local
github.com/greenpau/go-authcrunch checkout that sits next to the
caddy-security directory in the filesystem tree. If caddy-security is at
<parent>/caddy-security, assume go-authcrunch is at
<parent>/go-authcrunch; from this repository, that path is
../go-authcrunch.
Use a Go module replacement when the user is aligning caddy-security changes
with parallel local go-authcrunch work. Read the currently required
go-authcrunch version from this repository's go.mod:
go list -m -f '{{.Version}}' github.com/greenpau/go-authcrunch
Then use that required version in the replacement command:
go mod edit -replace github.com/greenpau/go-authcrunch@<go-authcrunch-version-from-go.mod>=../go-authcrunch
The replacement shim in go.mod should generally stay while caddy-security
depends on local go-authcrunch changes that are still in progress.
In the normal sequence, go-authcrunch changes first, such as implementing a
new feature, and then caddy-security changes to use that feature through the
local replacement. After there are no more go-authcrunch changes, and the
target go-authcrunch version has been updated, remove the local replace
directive, sync caddy-security to the new go-authcrunch version, and test.
make sync removes local go-authcrunch replacements after updating references.
Asset and Documentation Scripts
assets/scripts/generate_downloads.sh rewrites Caddy download links in
README.md using VERSION, github.com/greenpau/caddy-security, and the
hard-coded github.com/greenpau/caddy-trace version. It is called by
make release-update-version and make license.
assets/scripts/update_doc_refs.sh reads ../go-authcrunch/VERSION, updates
go-authcrunch references in CONTRIBUTING.md, Makefile, and go.mod, removes
local go-authcrunch replace directives from go.mod, then runs go mod tidy,
go mod verify, make, and make test. make sync invokes this script.
Use make sync only for an explicit go-authcrunch reference refresh. The script
assumes a sibling ../go-authcrunch checkout and uses BSD/macOS sed -i ''
syntax.
Release and Version Targets
Treat release targets as human-operator actions unless the user explicitly asks
for a release workflow.
make release-git-check runs go mod tidy, go mod verify, requires the
current branch to be main, and requires a clean git worktree.make release-update-version runs versioned -patch, refreshes README
download links, and stages VERSION, README.md, CONTRIBUTING.md, and
Makefile.make release-git-commit creates a release commit, creates an annotated tag,
pushes commits, and pushes tags.make release chains release-git-check, build, release-update-version,
and release-git-commit..github/workflows/release.yml runs GoReleaser on v* tags or manual
dispatch. .goreleaser.yaml builds cmd/authcrunch for Linux, Windows, and
Darwin on amd64 and arm64.
Never push commits or tags, create release tags, or run the chained release
target unless the user has explicitly requested that action.
Other Targets
make upgrade runs go get -u ./... and go mod tidy; use it only for an
explicit dependency upgrade.make license applies the repository license header to every Go file with
versioned and regenerates download links; expect broad source changes.make logo requires GraphicsMagick gm and rewrites
assets/docs/images/logo.png.make linter is currently a placeholder and does not run golint.
Generated Artifacts
Do not treat generated outputs as source changes unless the user explicitly asks
to update or commit them.
bin/authcrunch is produced by build/devbuild targets..coverage/coverage.html, .coverage/coverage.out,
.coverage/test_output.jsonl, and .coverage/test_output.html are produced
by make test and report targets. They contain coverage stats and test output
reports; the HTML files are browser-friendly review artifacts.../xcaddy-caddy-security is produced by make devbuild outside the repo.
Formatted Caddyfiles, README download links, VERSION, go.mod, and
go.sum can be intentional source changes depending on the target. Review the
diff before deciding whether to keep them.
CI Notes
The build workflow runs on Ubuntu with Go 1.25.x. It installs make and
libnss3-tools, runs make dep, go mod tidy, go mod verify,
go mod download, make test || true, make test, then make coverage, and
uploads .coverage/coverage.html.
The CLA workflow may update assets/cla/signatures.json through GitHub
automation. Do not edit CLA signatures or consent files unless the user asks.
