notcrawl/docs/distribution.md

Distribution

notcrawl ships through GitHub Releases, Homebrew tap updates, and optional Cloudsmith APT/RPM repositories.

Local Checks

go test ./...
go build ./cmd/notcrawl

Also smoke the crawlkit control and non-interactive TUI surfaces before a tag:

notcrawl metadata --json
notcrawl status --json
notcrawl doctor --json
notcrawl tui --json --limit 10

The CI workflow runs the same control-surface smoke checks, plus dependency verification, gofmt, go vet, tests, a GoReleaser snapshot build, and CodeQL.

If GoReleaser is installed:

make release-snapshot

That creates local snapshot archives, checksums, .deb, and .rpm packages under dist/ without publishing.

Release Notes

GitHub uses Release Drafter to auto-label PRs and generate release notes from merged pull requests. The release workflow publishes the Release Drafter output for the pushed tag, then uploads the GoReleaser artifacts to that release.

Tagged Release

Create and push a semver tag:

git tag v0.1.0
git push origin v0.1.0

The release workflow:

1. runs tests
2. builds GoReleaser artifacts
3. publishes Release Drafter notes for the tag
4. uploads GitHub release assets
5. optionally publishes APT/RPM packages to Cloudsmith
6. updates the Homebrew tap

Required Secrets

• HOMEBREW_TAP_GITHUB_TOKEN: token that can push to the tap repository
• CLOUDSMITH_API_KEY: optional; enables package publishing

Optional Variables

• HOMEBREW_TAP_REPO: defaults to vincentkoc/tap
• CLOUDSMITH_APT_TARGETS: comma-separated targets like ubuntu/jammy,debian/trixie
• CLOUDSMITH_DISTRIBUTION and CLOUDSMITH_RELEASE: legacy single APT target
• CLOUDSMITH_RPM_DISTRIBUTION: defaults to el
• CLOUDSMITH_RPM_RELEASE: defaults to 9

Manual Reruns

If Cloudsmith publish fails after GitHub release assets exist:

gh workflow run publish-apt.yml -f tag_name=v0.1.0
gh workflow run publish-rpm.yml -f tag_name=v0.1.0

If the Homebrew tap update fails:

gh workflow run homebrew-tap.yml -f tag_name=v0.1.0