searxng-mcp-go/docs/agents/release.md
XLion 6d6e884cee
docs: grouped mechanical documentation cleanup (#482)
* 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
2026-07-14 03:17:51 +08:00

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 as GPG_FINGERPRINT for GoReleaser.
  • HOMEBREW_TAP_SSH_KEY — SSH key with push access to xlionjuan/homebrew-tap. GoReleaser uses it to push the updated cask via ssh://[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. The permissions: contents: write declaration 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 from GPG_PRIVATE_KEY at 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:

  1. go mod download and go mod verify
  2. go mod tidy and git diff --exit-code -- go.mod go.sum (dirty-module check)
  3. go build -o /tmp/searxng-mcp-go .
  4. go test -race -shuffle=on ./...
  5. go tool govulncheck ./...
  6. golangci/golangci-lint-action runs 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 example v1.0.4 or v1.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

  1. Patch the version constant in main.go to the new version.

  2. Commit with a non-interactive message:

    git commit -m "chore: bump version to vX.Y.Z"
    
  3. Create an annotated tag:

    git tag -a vX.Y.Z -m "Release vX.Y.Z"
    
  4. 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.zst archives for linux/amd64 and linux/arm64
  • Static binaries with CGO_ENABLED=0 and netgo/osusergo build 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:, and chore: 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.