* docs: grouped mechanical documentation cleanup - docs/agents/domain.md: Add missing ADR entries 013-015 to the listing - docs/agents/release.md: Correct step 6 to reference golangci/golangci-lint-action - docs/INSTALL.md: Add note about q parameter redaction in GET fallback errors Ref: #474, #478 * docs: move URL redaction note outside code block for proper rendering
5.1 KiB
Release Workflow
Run this workflow only when the user explicitly asks for a release and the target version is known or confirmed.
Required Secrets
The release workflow expects the following repository secrets to be
configured under Settings → Secrets and variables → Actions before a
release tag is pushed:
GPG_PRIVATE_KEY— ASCII-armored GPG private key used to sign the Homebrew tap commit. The workflow imports it into the default keyring (release.yml"Import GPG Key" step), derives the fingerprint at runtime, and exports it asGPG_FINGERPRINTfor GoReleaser.HOMEBREW_TAP_SSH_KEY— SSH key with push access toxlionjuan/homebrew-tap. GoReleaser uses it to push the updated cask viassh://[email protected]/xlionjuan/homebrew-tap.git.
GPG_PRIVATE_KEY and HOMEBREW_TAP_SSH_KEY are not generated by this
repository. Obtain and rotate them out of band. A release run that
finds either secret missing will fail in either the GPG import step
(secret unset) or the GoReleaser push to the tap (auth refused).
Auto-Provided Tokens
The release workflow also references credentials that GitHub Actions
injects automatically and that do not need to be configured under
Settings → Secrets and variables → Actions:
GITHUB_TOKEN— created by GitHub Actions for every workflow run and scoped to the repository that triggered the run. The release workflow passes it to GoReleaser (.github/workflows/release.yml"Run GoReleaser" step) so GoReleaser can create the GitHub Release. Thepermissions: contents: writedeclaration at the top of the workflow grants the scopes that this token receives; no additional setup is required.GPG_FINGERPRINT— not a secret. The "Import GPG Key" step derives the fingerprint fromGPG_PRIVATE_KEYat runtime and appends it to$GITHUB_ENV; GoReleaser then reads it from the environment.
Cosign Step
.github/workflows/release.yml installs Cosign via
sigstore/cosign-installer, but the binary is not currently invoked by
any subsequent step. Treat the install step as reserved for future
signature blobs; if you add a step that signs release artifacts with
Cosign, document the key material, signing identity, and verification
instructions in this file in the same change.
Pre-Release Gates
.github/workflows/release.yml runs the following gates inside the
release job and before GoReleaser publishes anything:
go mod downloadandgo mod verifygo mod tidyandgit diff --exit-code -- go.mod go.sum(dirty-module check)go build -o /tmp/searxng-mcp-go .go test -race -shuffle=on ./...go tool govulncheck ./...golangci/golangci-lint-actionruns golangci-lint v2.12.2
If any of these fail, the job stops before GoReleaser runs, so a broken tag cannot publish a release.
GoReleaser's before.hooks runs go mod download
(.goreleaser.yaml:6-8). After GoReleaser finishes, the job cleans up
the imported GPG key.
Version Rules
- Tag style:
v{major}.{minor}.{patch}, for examplev1.0.4orv1.1.0. - Do not use
-beta,-rc, or other suffixes. - Do not infer the target version. If it is missing or ambiguous, ask before editing release files.
Steps
-
Patch the
versionconstant inmain.goto the new version. -
Commit with a non-interactive message:
git commit -m "chore: bump version to vX.Y.Z" -
Create an annotated tag:
git tag -a vX.Y.Z -m "Release vX.Y.Z" -
Push main and the tag:
git push origin main git push origin vX.Y.Z
Pushing the tag triggers .github/workflows/release.yml.
GoReleaser Outputs
The .goreleaser.yaml configuration produces:
tar.zstarchives forlinux/amd64andlinux/arm64- Static binaries with
CGO_ENABLED=0andnetgo/osusergobuild tags - Archive names matching
searxng-mcp-go_v{Version}_{Os}_{Arch} - Binary,
README.md,LICENSE, and checksums file in release artifacts - GitHub Release with automatic prerelease detection and
make_latest: true - Homebrew tap update for
xlionjuan/homebrew-tap - Auto-generated changelog excluding
docs:,test:, andchore:commits
Build Tags
The build uses netgo and osusergo build tags
(.goreleaser.yaml:21-23) together with CGO_ENABLED=0 to produce fully
static binaries. These tags force Go's DNS resolver and OS user lookup to
use the pure Go implementations instead of cgo, eliminating libc and
nsswitch dependencies at runtime. The result is a portable binary
suitable for minimal containers (Alpine, distroless, scratch). Do not
remove them without verifying that the resulting binary still works on
the target Linux distributions (Alpine, Debian, etc.).
Version Injection
GoReleaser ldflags override the hardcoded main.go version at build time:
-X main.version=v{{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}
The hardcoded main.go value is used by --version only when the binary is not
built by GoReleaser. Do not add ldflags for variables that main.go does not
declare — go silently ignores unknown -X targets, but stale ldflags drift
out of sync with the source the moment a variable is renamed or removed.