CodeIssuesPullsCIStacksSearchBranchesTags
Commits

docs/operations/release.md

Release Checklist

For maintainers. Using T3 Code? See docs/user.

This document covers the unified release workflow for stable and nightly desktop releases.

What the workflow does

  • Workflow: .github/workflows/release.yml
  • Triggers:
    • manual workflow_dispatch with channel=stable, the normal way to ship stable
    • push tag matching v*.*.* for a stable release of an explicit commit
    • scheduled nightly check every 30 minutes
    • manual workflow_dispatch with channel=nightly
  • A manual stable release builds the commit of the latest published nightly, not main HEAD. Nightly is the release candidate: verify the nightly, then promote it. Merges to main keep landing while you verify and never leak into the stable build.
    • The version defaults to the one the nightly previewed (0.0.39-nightly.* ships as 0.0.39). Pass the version input to override it, for example for a minor bump.
    • The stable tag is created on the nightly's commit when the GitHub Release is published.
    • Pushing a vX.Y.Z tag by hand still works and builds exactly the tagged commit. Use it when the commit to ship is not the latest nightly, such as a cherry-picked fix on a release branch.
  • Runs lint, typecheck, and tests alongside artifact builds. Publishing waits for every check.
  • Reads the shared production T3 Connect relay URL and Clerk client configuration before packaging clients.
  • Builds four artifacts in parallel for both channels:
    • macOS arm64 DMG
    • macOS x64 DMG
    • Linux x64 AppImage
    • Windows x64 NSIS installer
  • Publishes one GitHub Release with all produced files.
    • Stable tags with a suffix after X.Y.Z (for example 1.2.3-alpha.1) are published as GitHub prereleases.
    • Only plain stable X.Y.Z releases are marked as the repository's latest release.
    • Nightly runs are always GitHub prereleases and never marked latest.
    • Automatically generated release notes are pinned to the previous tag in the same channel, so stable compares to the previous stable tag and nightly compares to the previous nightly tag.
  • Includes Electron auto-update metadata (for example latest*.yml, nightly*.yml, and *.blockmap) in release assets.
  • Publishes the CLI package (apps/server, npm package t3) with OIDC trusted publishing from the same workflow file:
    • stable releases publish npm dist-tag latest
    • nightly releases publish npm dist-tag nightly
  • Deploys the hosted web app to Vercel only after a release is published:
    • stable releases are aliased to the latest hosted app channel
    • nightly releases are aliased to the nightly hosted app channel
  • Signing is optional and auto-detected per platform from secrets.

Required release credentials

Stable releases require these GitHub Actions secrets in addition to the platform and deployment credentials documented below:

  • RELEASE_APP_ID
  • RELEASE_APP_PRIVATE_KEY

The finalize job uses them to commit and push aligned package versions to main as the Release App. GitHub Release publication uses the repository-scoped workflow token so it has a rate-limit quota independent from the shared Release App installation.

T3 Connect relay deployment

The relay is a shared control plane versioned separately from client releases. Stable and nightly client builds must point at the same relay so users see the same linked environments when switching release channels.

.github/workflows/deploy-relay.yml deploys Alchemy stage prod on every push to main. The release workflow reads the relay URL and Clerk client configuration from the existing production GitHub Actions environment before building desktop, CLI, or hosted web artifacts.

Required repository variables shared by relay deployments:

  • CLOUDFLARE_ACCOUNT_ID
  • PLANETSCALE_ORGANIZATION
  • AXIOM_ORG_ID

Required repository secrets shared by relay deployments:

  • CLOUDFLARE_API_TOKEN
  • PLANETSCALE_API_TOKEN_ID
  • PLANETSCALE_API_TOKEN
  • AXIOM_TOKEN

Required production environment variables:

  • RELAY_API_ZONE_NAME
  • RELAY_TUNNEL_ZONE_NAME
  • CLERK_PUBLISHABLE_KEY
  • CLERK_JWT_AUDIENCE
  • CLERK_JWT_TEMPLATE
  • CLERK_CLI_OAUTH_CLIENT_ID
  • APNS_ENVIRONMENT
  • APNS_TEAM_ID
  • APNS_KEY_ID
  • APNS_BUNDLE_ID

Optional production environment variables:

  • RELAY_DOMAIN when overriding the derived relay.<RELAY_API_ZONE_NAME> domain

Required production environment secrets:

  • CLERK_SECRET_KEY
  • APNS_PRIVATE_KEY

The account-scoped repository credentials are consumed by Alchemy while provisioning relay stages; they are not bound into the relay Worker. The production deployment uses an Axiom personal access token, so AXIOM_ORG_ID must accompany AXIOM_TOKEN. The prod stage owns the retained PlanetScale database. Local personal stages provision isolated branches from it and are never deployed by CI. Production adopts the configured relay API and tunnel DNS zones as retained Cloudflare resources. Personal stages reference the production-owned zones.

Developers deploy personal stages locally rather than through pull-request automation:

sh
1vp run --filter t3code-relay deploy -- --stage "$USER" --env-file .env.local

Marketing site deployment

After a nightly release is published, the release workflow deploys the same commit to the marketing site's Vercel production project. Stable releases do not deploy the marketing site because they can promote an older nightly commit.

The job looks up the t3code-marketing project using the existing VERCEL_TOKEN and VERCEL_ORG_ID secrets. It also respects the optional VERCEL_TEAM_SLUG variable. The Vercel project's root directory must be apps/marketing. Git deployments remain disabled in apps/marketing/vercel.ts.

Hosted web app release deployment

The hosted app is intentionally not deployed by Vercel's Git integration. The web project disables automatic Git deployments in apps/web/vercel.ts via git.deploymentEnabled: false, and .github/workflows/release.yml deploys the web app with Vercel CLI after the GitHub Release succeeds.

Required GitHub Actions secrets:

  • VERCEL_TOKEN
  • VERCEL_ORG_ID
  • VERCEL_PROJECT_ID

Optional GitHub Actions variables:

  • VERCEL_TEAM_SLUG: overrides the Vercel CLI scope when the team slug is preferred over the VERCEL_ORG_ID secret.
  • T3CODE_WEB_ROUTER_URL: defaults to https://app.t3.codes.
  • T3CODE_WEB_LATEST_DOMAIN: defaults to latest.app.t3.codes.
  • T3CODE_WEB_NIGHTLY_DOMAIN: defaults to nightly.app.t3.codes.

Required Vercel domains:

  • app.t3.codes: the router domain users open, updated by stable releases.
  • latest.app.t3.codes: channel alias updated by stable releases.
  • nightly.app.t3.codes: channel alias updated by nightly releases.

The router domain uses apps/web/vercel.ts routes. Users opt into a channel by visiting /__t3code/channel?channel=latest or /__t3code/channel?channel=nightly; the router stores the t3code_web_channel cookie and rewrites future requests on app.t3.codes to the matching channel alias.

The release deploy job rewrites release package versions before upload so the hosted app's About panel renders the release version. Stable deploys alias the same deployment to both the latest channel and the router domain so the router rules stay current. Nightly deploys only alias the nightly channel. The job also passes VITE_HOSTED_APP_CHANNEL=latest|nightly, which renders the hosted update track selector in the About panel. Changing the selector navigates through /__t3code/channel on the router domain so the user's channel cookie is updated before redirecting to the hosted app root.

One-time Vercel dashboard setup:

  1. Confirm the web project root directory remains apps/web.
  2. Add the three domains above to the web project.
  3. Disable automatic Git deployments in the dashboard if desired; the committed vercel.ts setting is the source-of-truth, but disconnecting Git in the dashboard is also safe.
  4. Run one stable release deployment, or manually alias the current stable deployment, so app.t3.codes points at a deployment containing the router rules in apps/web/vercel.ts. Future stable releases keep this alias current.

Nightly builds

  • Workflow: .github/workflows/release.yml
  • Triggers:
    • scheduled check every 30 minutes
    • manual workflow_dispatch with channel=nightly
  • Automatic nightlies require new commits and at least six hours since the last nightly was published, including manual nightlies.
  • Manual nightlies bypass the time and change checks. Nightly runs remain serialized. Scheduled runs wait for an active nightly to finish, then check the publication gap before building.
  • Runs the same desktop quality gates and artifact matrix as the tagged release flow.
  • Publishes a GitHub prerelease only:
    • current tag format: vX.Y.Z-nightly.YYYYMMDD.<run_number>
    • nightly-v... is accepted only as a legacy previous-nightly tag
    • release name includes the short commit SHA
    • make_latest is always false
  • Uses the next stable patch version as the nightly base. For example, 0.0.17 produces nightlies on 0.0.18-nightly.*.
  • Publishes Electron auto-update metadata to the dedicated nightly updater channel, so desktop users can opt into that track independently from stable.
  • Publishes the CLI package (apps/server, npm package t3) to the nightly npm dist-tag using the same nightly version.
  • Does not commit version bumps back to main.

Server self-update release invariant

Connected servers update to the client's exact version, not to an npm dist-tag. Every released desktop or hosted client version must therefore have a matching t3@<version> package available on npm before users can receive that client.

The workflow enforces this ordering:

  1. publish_cli publishes the exact stable or nightly version to npm.
  2. release depends on publish_cli before exposing desktop artifacts in GitHub Releases.
  3. deploy_web depends on release before moving the hosted channel to the new client.

Preserve these dependencies when changing the release graph. Publishing a client first would leave the Update server action targeting a package version that does not exist yet.

For a release smoke test, confirm npm view t3@<version> version returns the expected version, then connect the new client to a server on the previous version and verify that the update action reconnects to the matching server. When the release adds database migrations, verify that the remote update applies them and reconnects. A failed trial must restore the database snapshot and restart the previous server. If the installed launcher does not support the target protocol, verify that the update stops before restart and run npx t3@<version> service update once on the server machine. Also test the manual or desktop-managed guidance when those environments are available.

Desktop auto-update notes

  • Updater runtime: apps/desktop/src/updates/DesktopUpdates.ts.
  • electron-updater adapter: apps/desktop/src/electron/ElectronUpdater.ts.
  • apps/desktop/src/main.ts only wires the updater layers into the desktop runtime.
  • Update UX:
    • Background checks run on startup delay + interval.
    • No automatic download or install.
    • The desktop UI shows a rocket update button when an update is available; click once to download, click again after download to restart/install.
  • Provider: GitHub Releases (provider: github) configured at build time.
  • Repository slug source:
    • T3CODE_DESKTOP_UPDATE_REPOSITORY (format owner/repo), if set.
    • otherwise GITHUB_REPOSITORY from GitHub Actions.
  • Required release assets for updater:
    • platform installers (.exe, .dmg, .AppImage, plus macOS .zip for Squirrel.Mac update payloads)
    • channel metadata: latest*.yml for stable releases, nightly*.yml for nightly releases
    • *.blockmap files (used for differential downloads)
  • macOS metadata note:
    • electron-updater reads latest-mac.yml on stable and nightly-mac.yml on nightly, for both Intel and Apple Silicon.
    • The workflow merges the per-arch mac manifests into one channel-specific mac manifest before publishing the GitHub Release.

Windows payload topology and update validation

Windows packages the bundled server and only its runtime-external/native dependency closure in resources/server.asar. Native modules and helper executables declared as unpacked by that archive must be present at the matching paths below resources/server.asar.unpacked. The Windows-native backend reads the archive in place through Electron. Packaged Windows builds also ship a Linux-only resources/wsl-runtime.tar.gz plus its SHA-256 sidecar. WSL verifies and extracts that archive into ~/.t3/wsl-runtime/sha256-<archive-digest> inside the selected distro, then reuses it for later launches of the same update. The Windows-side wsl-server-tree/<version> extraction remains a fallback and is removed after the distro-local runtime passes preflight.

Windows keeps JavaScript and package metadata inside app.asar and unpacks only native libraries and helper executables. Avoid enabling whole-package smart unpacking: each loose file adds work to NSIS installation and counts against the payload limit.

The artifact builder rejects a Windows package when any of these invariants break:

  • resources/server.asar is absent or does not contain the server entry.
  • Any file marked unpacked in the ASAR header is absent from resources/server.asar.unpacked.
  • On same-architecture Windows builds, the packaged primary cannot load the fff native library from inside server.asar through its .unpacked sibling.
  • The isolated, extracted sidecar cannot load the server entry with plain Node.
  • A Windows build with a WSL node-pty prebuild omits the WSL archive or SHA-256 sidecar, the sidecar digest does not match the emitted archive, or required Linux runtime members are absent.
  • The emitted WSL archive contains Windows/Darwin node-pty payloads, ConPTY, pnpm install metadata, or Windows-only FFF, ffi-rs, or msgpackr bindings.
  • The external Windows resource monitor is absent.
  • The unpacked Windows application contains more than 80 files.

Cross-architecture Windows builds retain every structural and extracted-sidecar check, but skip executing the target Electron binary. A same-architecture build for each release target must exercise the primary native-load probe.

NSIS differential packaging remains enabled. A sidecar layout transition can produce a larger one-time download; subsequent small releases retain their blockmaps, with a 60 MB maximum for a representative sidecar-to-sidecar update.

0) npm OIDC trusted publishing setup (CLI)

The workflow invokes node apps/server/scripts/cli.ts publish after aligning package versions. That script temporarily prepares the t3 package, then runs vp pm publish --filter t3 ... from the repository root so workspace publish configuration is applied correctly.

Checklist:

  1. Confirm npm org/user owns package t3 (or rename package first if needed).
  2. In npm package settings, configure Trusted Publisher:
    • Provider: GitHub Actions
    • Repository: this repo
    • Workflow file: .github/workflows/release.yml
    • Environment (if used): match your npm trusted publishing config
  3. Ensure npm account and org policies allow trusted publishing for the package.
  4. Create release tag vX.Y.Z and push; workflow will:
    • align the release package versions to X.Y.Z
    • build web + server
    • invoke the CLI publish script with npm dist-tag latest
  5. Nightly runs invoke the same publish script with npm dist-tag nightly.

1) Release validation and unsigned builds

There is no dry-run tag path. Pushing any accepted non-nightly tag, including v0.0.0-test.1, classifies the run as the stable channel. It publishes t3 with npm dist-tag latest, creates a real GitHub Release, aliases the hosted app to latest.app.t3.codes and app.t3.codes, and can commit a version bump to main in the finalize job. Do not push a test tag to validate the workflow.

The workflow has no non-publishing workflow_dispatch mode. Use normal CI or local quality gates to validate checks and builds without shipping. To exercise the complete release graph at lower stable risk, manually dispatch channel=nightly; this still publishes a real nightly npm package, GitHub prerelease, desktop updater release, hosted nightly alias, and marketing site, but it does not update stable app aliases or commit a version bump to main. Only run it when a real nightly release is acceptable.

Manual channel=stable is also a real stable-channel release. Omitting signing secrets only makes platform artifacts unsigned; it does not prevent publication.

2) Apple signing + notarization setup (macOS)

Required secrets used by the workflow:

  • CSC_LINK
  • CSC_KEY_PASSWORD
  • APPLE_API_KEY
  • APPLE_API_KEY_ID
  • APPLE_API_ISSUER
  • MACOS_PROVISIONING_PROFILE (base64-encoded provisioning profile with Associated Domains)

Required repository variables:

  • APPLE_TEAM_ID

Optional repository variables:

  • CLERK_PASSKEY_RP_DOMAINS: comma-separated RP-domain override. By default, the build derives the domain from the production Clerk publishable key.

Checklist:

  1. Apple Developer account access:
    • Team has rights to create Developer ID certificates.
  2. Create an explicit App ID for com.t3tools.t3code and enable Associated Domains.
  3. Create a Developer ID Application certificate and a compatible provisioning profile for that App ID with Associated Domains enabled.
  4. Export the certificate + private key as .p12 from Keychain.
  5. Base64-encode the .p12 and store as CSC_LINK.
  6. Base64-encode the provisioning profile and store it as MACOS_PROVISIONING_PROFILE.
  7. Store the .p12 export password as CSC_KEY_PASSWORD, and set APPLE_TEAM_ID to the 10-character Apple Developer Team ID.
  8. In App Store Connect, create an API key (Team key).
  9. Add API key values:
    • APPLE_API_KEY: contents of the downloaded .p8
    • APPLE_API_KEY_ID: Key ID
    • APPLE_API_ISSUER: Issuer ID
  10. Complete the Clerk Native API and AASA setup in T3 Connect setup.
  11. Re-run a tag release and confirm macOS artifacts are signed/notarized and contain the expected com.apple.developer.associated-domains entitlement.

Notes:

  • APPLE_API_KEY is stored as raw key text in secrets.
  • The workflow writes it to a temporary AuthKey_<id>.p8 file at runtime.
  • The workflow decodes MACOS_PROVISIONING_PROFILE, validates it with security cms, and passes it to the desktop packager.

3) Azure Trusted Signing setup (Windows)

Required secrets used by the workflow:

  • AZURE_TENANT_ID
  • AZURE_CLIENT_ID
  • AZURE_CLIENT_SECRET
  • AZURE_TRUSTED_SIGNING_ENDPOINT
  • AZURE_TRUSTED_SIGNING_ACCOUNT_NAME
  • AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME
  • AZURE_TRUSTED_SIGNING_PUBLISHER_NAME

Checklist:

  1. Create Azure Trusted Signing account and certificate profile.
  2. Record ATS values:
    • Endpoint
    • Account name
    • Certificate profile name
    • Publisher name
  3. Create/choose an Entra app registration (service principal).
  4. Grant service principal permissions required by Trusted Signing.
  5. Create a client secret for the service principal.
  6. Add Azure secrets listed above in GitHub Actions secrets.
  7. Re-run a tag release and confirm Windows installer is signed.

4) Ongoing release checklist

  1. Pick the latest nightly and verify it: run the smoke test above against its artifacts and check the nightly channel for regressions.
  2. Dispatch the Release workflow with channel=stable. Leave version empty unless the version should differ from the one the nightly previewed.
  3. Confirm the Resolve release commit notice names the nightly tag and commit you verified. If a newer nightly published in between, the run builds that one instead.
  4. Verify workflow steps:
    • preflight passes
    • release quality checks pass
    • all matrix builds pass
    • publish_cli publishes the exact release version before the release job
    • release job uploads expected files
  5. Smoke test downloaded artifacts.

5) Troubleshooting

  • macOS build unsigned when expected signed:
    • Check all Apple secrets plus APPLE_TEAM_ID are populated and non-empty.
    • Confirm the provisioning profile belongs to APPLE_TEAM_ID.com.t3tools.t3code and includes Associated Domains.
  • Windows build unsigned when expected signed:
    • Check all Azure ATS and auth secrets are populated and non-empty.
  • Build fails with signing error:
    • Retry with secrets removed to confirm unsigned path still works.
    • Re-check certificate/profile names and tenant/client credentials.