Con Release

Use this skill when preparing a release, pushing a release tag, checking a release workflow, or recovering a failed publication. The release workflow is the source of truth; do not treat a green build on one platform as a release.

Release contract

• Release from main only.
• Prepare CHANGELOG.md before tagging. The top section must be the next unreleased beta and every PR-derived item must credit its GitHub author.
• Push exactly one immutable tag. Use v0.1.0-beta.N for beta, v0.1.0-dev.N for dev, and the project stable tag when stable is explicitly approved.
• A tag push starts the macOS, Linux, Windows, and Flatpak workflows. Platform jobs create or update one GitHub draft release and upload their own assets.
• macOS binaries build on native ARM/Intel runners. Both bundles then transfer to separate ARM packaging jobs for signing, notarization, and ticket stapling. The transfer archive preserves executable bits and symlinks; metadata and binary architectures are checked before signing. Intel CLI smoke verification on ARM uses Rosetta, not a cross-build. Only macos-* finalized artifacts may be downloaded by publication jobs; native-app-* archives are internal.
• A release is public only after all required platform assets and release-gate checks pass. Installers and updaters must never consume a draft.
• Signed feeds are prepared at release-staging/<tag>/appcast/, not the live updater endpoints. The finalizer publishes the release, verifies anonymous access to the exact download URLs, then merges canonical feeds and updates Homebrew. Public release metadata alone does not prove updater availability.
• Never delete and recreate a tag to repair a release. Fix the workflow or rerun the affected workflow against the same commit.

Before tagging

Run these checks from a clean checkout:

git fetch origin main --tags
git switch main
git pull --ff-only origin main
git status --short
git tag --sort=-v:refname | rg '^v[0-9]+\\.[0-9]+\\.[0-9]+-(beta|dev)\\.' | head
gh release list --limit 5

Confirm the next version is greater than the latest released version, the changelog heading matches it, and git status --short is empty. Run the release-relevant test suite before tagging; platform packaging tests belong in the release workflows and must not be replaced by a local cross-build.

Publish

Create an annotated tag at the verified main commit and push only that tag:

git tag -a v0.1.0-beta.N origin/main -m "Release v0.1.0-beta.N"
git push origin refs/tags/v0.1.0-beta.N

Track the four tag-triggered workflows:

gh run list --limit 20 --json workflowName,status,conclusion,headBranch,headSha,url \\
  --jq '.[] | select(.headBranch == "v0.1.0-beta.N")'

Do not publish a draft manually while a required platform is still running or failed. The finalizer checks the newest matching run for each required platform, then validates assets, checksums, appcasts, and public installer scripts before promoting the draft.

Verify the public result

After the finalizer succeeds, verify the public contract:

gh release view v0.1.0-beta.N --json isDraft,isPrerelease,publishedAt,assets,url

For a beta, expect isDraft: false and the repository's beta-channel release semantics. Confirm the expected macOS arm64/x86_64 DMGs and ZIPs, Linux tarball, Windows ZIP, and checksum files are present. Check the beta appcasts and the public installer endpoints if they are part of the release:

curl -fsSL https://con-releases.nowledge.co/install.sh >/dev/null
curl -fsSL https://con-releases.nowledge.co/install.ps1 >/dev/null

Recovery

• If dependency setup stalls, inspect the active step before assuming a slow build or Apple outage. macOS/Linux Zig setup must use scripts/ci/install-zig.sh with a workflow step deadline; run its regression suite before changing bootstrap policy. Connection timeouts alone do not bound downloads.
• If a platform workflow is cancelled, rerun that exact workflow run; do not push a second tag when the tagged workflow is still correct. If the workflow itself needs a fix, merge it to main and use a new immutable tag instead; rerunning an old tag still uses its old workflow. Carry forward release notes and author credits from any cancelled, unpublished release attempts.
• If all platform workflows succeeded but the release remains draft, inspect the latest Finalize release run. Rerun only the finalizer after confirming the release gate inputs are complete.
• Missing Actions results are retried with a recent-run fallback and exact tag/SHA matching. Persistent query errors must fail visibly, not look like a successful publication. Recover staged releases with gh workflow run release-finalize.yml --ref main -f tag=<tag>.
• If promotion succeeded but feed publication failed, rerun the finalizer. It validates public releases too, preserves newer feed entries, and never needs a new tag. Legacy tags without staged metadata require their original finalizer and explicit payload/feed checks instead.
• If an asset is missing, rerun the platform that owns it and verify its checksum before promotion.
• On the split macOS workflow, rerun failed packaging jobs without rebuilding successful native bundles while their seven-day artifacts remain available. Rerunning an old tag executes that tag's workflow/scripts, not fixes on main. Do not expect the split packaging fix to apply retroactively to beta.131.
• If the release is already public, later finalizer runs are harmless and must not change its prerelease/channel semantics.
• Record a workflow or release incident in postmortem/ when the failure exposes a new invariant or requires manual recovery.
• An accepted notarization is not a completed package. stapler must download and attach its ticket, then validation must succeed. The macOS scripts retry ticket-service exit 68 up to four attempts with 10/20/40-second delays; other failures stop immediately. Do not bypass ticket validation to recover a draft.

Common mistakes

• Do not tag from a stale local main.
• Do not use --force on release tags.
• Do not mark beta releases as prereleases unless the channel policy changes; current installers use the public latest beta semantics.
• Do not assume a draft URL or an uploaded asset means the release is public.
• Do not use a repository-wide GitHub Actions concurrency group for finalizer events; each source completion must remain observable.