# Scripts And Automation

> 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.

- Skill: `greenpau/scripts-and-automation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add greenpau/scripts-and-automation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/greenpau/scripts-and-automation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security, Coding & Dev Tools
- Author: greenpau (https://skillmd.com/u/greenpau)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/greenpau/scripts-and-automation

---


# 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`:

```bash
go list -m -f '{{.Version}}' github.com/greenpau/go-authcrunch
```

Then use that required version in the replacement command:

```bash
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.