Skip to content

publishing.md

Latest commit

 

History

History
125 lines (102 loc) · 6.15 KB

publishing.md

File metadata and controls

125 lines (102 loc) · 6.15 KB
Raw

Publishing Crawlkit

crawlkit is a Go library with the optional crawlctl CLI. Releases use the fleet release-go-cli workflow from openclaw/release-workflows. The workflow verifies fleet-signed tags and owns Developer ID signing, notarization, independent artifact verification, and GitHub Release publication. Create and verify the annotated tag with the fleet release key only after a successful dry run. Binary signing credentials remain in the workflow.

Published versions and signed CLI assets are listed on GitHub Releases and the module is available from the Go proxy. Release notes match the corresponding dated section in CHANGELOG.md.

A second dispatch for v0.14.7 rebuilt the payload and correctly failed its comparison with the existing public release; it left a separate unpublished draft. See the incident evidence.

Release assets

The archive prefix is the repository name; the executable inside every archive is crawlctl.

Platform Asset
macOS Apple Silicon crawlkit_<version>_darwin_arm64.tar.gz
macOS Intel crawlkit_<version>_darwin_amd64.tar.gz
Linux arm64 crawlkit_<version>_linux_arm64.tar.gz
Linux amd64 crawlkit_<version>_linux_amd64.tar.gz
All platforms checksums.txt
Release evidence ASSET-INVENTORY.json, SIGNING-MANIFEST.json, RELEASE-NOTES.md

The fixed macOS code identifier is org.openclaw.crawlctl, and the required signing identity is Developer ID Application: OpenClaw Foundation (FWJYW4S8P8). The workflow signs each native Mach-O with the hardened runtime, submits it for notarization, and independently verifies both architectures before publication. Both native macOS binaries require macOS 13.0 or later, matching the Go 1.27 deployment target. Before the shared workflow builds artifacts, the caller builds both architectures with CGO disabled, checks each LC_BUILD_VERSION using otool -l, and confirms notarization access with a read-only xcrun notarytool history. crawlkit has no universal macOS archive, nFPM package, or Homebrew handoff.

Release checklist

For release-build validation without publication, dispatch a dry run on the current green main head using the current version:

gh workflow run release-unified.yml --repo openclaw/crawlkit --ref main -f version=0.17.1 -f dry_run=true

Dry runs build, sign, notarize, and independently verify the current protected head. They allow an existing version but create no Git tag or GitHub release. The default remains a real release, which requires an unused version.

  1. Confirm the repository can access all five required Actions secrets: MACOS_SIGNING_P12, MACOS_SIGNING_P12_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY_P8. The shared workflow validates them before creating a tag.

  2. Choose an unused version and prepare a release PR from the current protected main head. Confirm the version is still unused and the changelog section is dated, then run (Node.js is required for the dispatch regression tests):

    make check
actionlint

  3. Merge the release-preparation PR and confirm its exact merge commit is green. Run the dry run above with the new version, then create the annotated version tag on that commit with the fleet release key. Verify it with git -c gpg.ssh.allowedSignersFile=.github/release-allowed-signers verify-tag vX.Y.Z before pushing it.

  4. Dispatch the unified workflow from the same protected main head:

    gh workflow run release-unified.yml --repo openclaw/crawlkit -f version=X.Y.Z

  5. Watch the exact workflow run through publication. A read-only preflight requires an annotated tag pointing directly to the workflow commit and rejects existing releases before the shared workflow verifies the tag signature. A repository-wide workflow lock spans preflight through publication, so queued dispatches (including X.Y.Z and vX.Y.Z) recheck state after the previous run finishes. The shared workflow freezes the verified tag, builds all four native archives, signs and notarizes the two macOS binaries, verifies the immutable draft independently on Apple Silicon and Intel, and publishes only the verified bytes.

  6. Confirm the GitHub Release notes match the dated changelog section. Download every release asset, verify checksums.txt, inspect both Linux binaries, and verify a downloaded macOS binary with:

    codesign --verify --strict --check-notarization -R=notarized ./crawlctl

  7. Prime and verify module proxy visibility:

    GOPROXY=https://proxy.golang.org GONOSUMDB= go list -m github.com/openclaw/crawlkit@vX.Y.Z
GOPROXY=https://proxy.golang.org go list -m github.com/openclaw/crawlkit@vX.Y.Z

  8. Merge the workflow's closeout PR, or otherwise add the next patch-version Unreleased changelog section.

Never delete or force-update a release tag or replace published assets. A Git tag is already a public Go module version, even when GitHub publication fails. Publication requires a fleet-signed tag on the exact workflow commit and no existing draft or public release. The shared pipeline freezes that tag before drafting. Tag lookup failures stop preflight; only an explicit 404 for the release lookup is treated as an unused release version.

After a failure, inspect the exact run, tag, release IDs, and retained artifacts before taking action. Do not rerun all jobs or redispatch a published version: rebuilding/re-signing does not reproduce the original verified archive bytes. Any recovery of an unpublished draft must retain its original payload and attestations, and requires a separately reviewed recovery decision. If those bytes cannot be recovered, use a new patch version. Old workflow runs retain their original workflow definition; this guard does not retrofit historical reruns. Keep the shared workflow's final byte-binding checks intact.

Use a patch version for narrow fixes on the existing API. Use a minor version for broad crawler infrastructure changes. If the module reaches v2, Go requires the module path to become github.com/openclaw/crawlkit/v2.