mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
* 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
135 lines
5.1 KiB
Markdown
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.
|