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.
• A release is public only after all required platform assets and release-gate checks pass. Installers and updaters must never consume a draft.
• 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 a platform workflow is cancelled, rerun that exact workflow run; do not push a second tag.
• 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.
• If an asset is missing, rerun the platform that owns it and verify its checksum before promotion.
• 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.

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.