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

135 lines
5.1 KiB
Markdown

# 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:
```bash
git commit -m "chore: bump version to vX.Y.Z"
```
3. Create an annotated tag:
```bash
git tag -a vX.Y.Z -m "Release vX.Y.Z"
```
4. Push main and the tag:
```bash
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:
```text
-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.