Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

28.4 KB
Raw Blame

Release and secrets

OpenScreen's release machinery lives in .github/workflows/prerelease.yml, promote.yml, and build.yml; its credentials are repository secrets and variables consumed by those workflows and the downstream package and Discord automations. This page is the operational reference for cutting releases and maintaining those credentials.

Release flow

Cut a release candidate

Run the Cut a release candidate workflow (prerelease.yml) with:

  • bump: patch, minor, or major; default minor.
  • rc_number: the numeric rc.N counter; default 1.
  • target_version: optional stable-version override such as 2.0.0.

The workflow computes X.Y.Z-rc.N, migrates items from Next Release to the vX.Y.Z milestone, creates or reuses release/vX.Y.Z, commits the prerelease version there, tags the frozen branch tip, explicitly dispatches build.yml at the RC tag, and announces the pre-release in the configured RC Discord channel.

build.yml does have a push: trigger on v* tags, but the release workflows do not rely on it. The dispatch is explicit and pinned to the tag, for two separate reasons:

  • Explicit, because a tag pushed with GITHUB_TOKEN does not fire build.yml's push: trigger in this org's setup — GitHub withholds that to stop workflows triggering each other in a loop. promote.yml does push the stable tag that way, so without the dispatch nothing would build.
  • Pinned with --ref, because the build must check out the tag, not the default branch. The version bump lives only on the release branch; main still carries the previous stable version, and build.yml's publish step would fail its guard (package.json version X does not match <tag>).

The two workflows push their tags with different credentials, which is deliberate: promote.yml uses GITHUB_TOKEN (a tag is a ref, not a file change), while prerelease.yml pushes the RC tag with OPENSCREEN_RELEASE_TOKEN. A GITHUB_TOKEN tag push is answered with remote: Internal Server Error — a 500, not a 403 — by a tag ruleset that rejects the Actions token, and that failure took down the whole v1.8.0-rc.1 cut, skipping the build trigger and the Discord announce with it.

Which whisper helper a build ships. build.yml does not compile whisper-stt-server: scripts/stage-whisper-stt.sh downloads it from a build-whisper-stt.yml run, which runs on the pushes that touch the helper. It takes the most recent successful run built from the same helper sources as the commit being packaged (the electron/native/whisper-stt tree, scripts/build-whisper-stt.sh and the workflow, compared by git object id), so the release branch's cherry-pick of a helper change matches the run built from main. No such run fails the build, with the command that makes one. Until 2026-09-30 it took the most recent artifact of any branch: v2.0.0-rc.1 shipped whatever main had last built, and a PR branch pushed an hour later would have decided what rc.2 shipped. So after cherry-picking a helper change, let a build-whisper-stt run of those sources finish before dispatching prerelease.yml.

RC tags are signed and notarized exactly like stable ones. That keeps testers out of xattr -rd com.apple.quarantine, and exercises the whole credential path on every candidate instead of first proving it on the promotion build.

Promote to stable

Run Promote RC to stable release (promote.yml) with:

  • rc_tag: required tag matching vX.Y.Z-(rc|beta|alpha).N.
  • release_notes_extra: optional text prepended to the stable Discord announcement.

The workflow validates the tag, closes the version milestone, checks out release/vX.Y.Z, changes package.json to the stable version, tags that branch tip, explicitly dispatches build.yml at the stable tag, then sets main to the stable version through a rebase-merged PR. That sync carries only the version: every fix on the release branch is a cherry-pick already on main. Replaying the whole branch instead stopped applying once main had moved on, and left main at 2.0.0 after v2.1.0 (#1312). A commit found on the release branch alone fails the step with its name, after the version sync. The build publishes signed/notarized artifacts when Apple credentials are complete; publication with OPENSCREEN_RELEASE_TOKEN emits the event that starts stable Homebrew, WinGet, Nix, and AUR workflows.

Before dispatching it, the RC has to have been through the manual end-to-end checklist. Nothing in promote.yml enforces that — it will promote an untested tag exactly as readily — so the gate is the operator. It is not a human-only gate either: the checks need real OS mouse and keyboard events, which an agent with the computer-use MCP supplies, so asking one to run it is a normal way to get it done. For a promote that means the whole file, not a risk-picked subset — the checklist asks for it in its own opening, and its results log shows why: webcam PiP, microphone, GIF and the AI sections have been scoped out of every run recorded so far, so "the sections this RC puts at risk" is precisely the judgement that keeps missing them. A Partial row is not a green light to dispatch. Mechanics and the rule on partial runs: AGENTS.md.

Release branches (the contract)

Every released version has exactly one frozen branch, named for the stable version, living from the first RC cut onward:

release/vX.Y.Z         created at rc.1, frozen through promote, kept for backports
release/vX.Y.Z-sync    ephemeral, created by promote from main to set its version

The name carries no -rc.N suffix. prerelease.yml and promote.yml must resolve the same ref, and every RC of a version re-cuts from this one branch.

  1. prerelease.yml creates the branch at rc.1 and reuses it for later RCs. It must never delete or recreate it: that would drop the cherry-picks and silently re-cut from main, defeating the freeze this contract exists to guarantee.
  2. promote.yml is the only automated writer that turns -rc.N into the stable version on the branch. A maintainer doing that by hand means the dispatch failed — see Manual fallback.
  3. main is never frozen. Development continues as usual; the release branch is the freeze.
  4. Cherry-picks during the RC window are committed manually by a maintainer (git checkout release/vX.Y.Z && git cherry-pick <sha>), then rerun prerelease.yml with the next rc_number to re-tag the branch tip.

Only cherry-picked bug fixes land on the branch between cut and promote. Features, refactors, and CI/docs changes are not applied — they live on main and ship in the next cycle. git log release/vX.Y.Z..main --oneline lists exactly what is not in the RC.

The branch stays around indefinitely: it is the frozen history of the release, useful for backports and forensics. Retiring one is a manual decision, taken only once a future major supersedes the line it froze.

This contract exists because of the v1.6.0 incident (2026-07-05): the original promote.yml checked out main, so the stable tag captured the post-RC tip of main rather than the RC snapshot. Twenty-three commits (Tiptap, NotesWindow, an in-recorder lint button, AI handoff) shipped in v1.6.0 without ever having been in v1.6.0-rc.1. The re-release the same day used release/v1.6.0 and cherry-picked only the commits that were genuinely safe.

Day-to-day branching, PR, and review procedure is maintained in the operational git workflow.

Manual fallback

When the dispatch UI is unavailable, the release can be cut from a shell. Set the version with .github/scripts/set-release-version.mjs — the same script both workflows call — and never with a hand-rolled sed on package.json: the script also writes package-lock.json, and a release commit that bumps only package.json ships a lockfile whose root version disagrees with the package it locks. npm ci does not reject that (the root version field is not a dependency, so the sync check ignores it), which is how three releases shipped with the mismatch before anyone noticed.

RC=1.5.0-rc.1                          # bump the rc.N for every later candidate

# Cut RC (skips milestone migration and Discord announce)
git checkout -b release/v1.5.0 main    # rc.2+: git checkout release/v1.5.0 instead
node .github/scripts/set-release-version.mjs "$RC"
bash .github/scripts/refresh-nix-npm-hash.sh   # needs Nix; the lockfile version is in the hash
git commit -am "chore(release): bump to $RC [skip ci]"
git push origin release/v1.5.0
git tag "v$RC" && git push origin "v$RC"

# Promote (skips milestone close and Discord announce)
git checkout release/v1.5.0
node .github/scripts/set-release-version.mjs 1.5.0
bash .github/scripts/refresh-nix-npm-hash.sh
git commit -am "chore(release): bump to 1.5.0 [skip ci]"
git push origin release/v1.5.0
git tag v1.5.0 && git push origin v1.5.0

A tag pushed with your own credentials does fire build.yml's push: trigger, so the release publishes on its own and no explicit dispatch is needed — that restriction only applies to GITHUB_TOKEN. Either way the same build.yml builds and publishes.

The fallback skips milestone migration/closure, release-branch automation, main synchronization, and Discord announcements, so the operator must preserve the freeze and the version/tag match by hand.

Backports / patch on a previous line

For a v1.4.2 while v1.5.0 is in flight:

  1. Branch release/1.4.x from the v1.4.0 (or v1.4.1) tag.
  2. Cherry-pick the fix commits.
  3. Push the branch, then git tag v1.4.2-rc.1 on the branch tip.
  4. git push origin release/1.4.x v1.4.2-rc.1 — build.yml works from any branch.

No new workflow code is needed; the tag-pushed trigger is branch-agnostic.

Issue tracking during a release cycle

  • Daily state: issues/PRs accumulate in the rolling Next Release milestone. merged-pr-bookkeeping.yml adds them automatically on PR merge; maintainers can also drag issues in by hand.
  • At RC cut: prerelease.yml snapshots Next Release into a versioned vX.Y.Z milestone. The rolling milestone is left open and empty for new work.
  • Between RC cut and promote: any PR that merges during the RC window lands back in the empty Next Release. It is not retroactively added to vX.Y.Z. If a critical fix lands, cut vX.Y.Z-rc.(N+1) instead of promoting.
  • At promote: promote.yml closes the vX.Y.Z milestone and uses its closed issues to populate the Discord release announcement.

Required release credential

OPENSCREEN_RELEASE_TOKEN

This fine-grained personal access token is used by prerelease.yml, promote.yml, and build.yml. It migrates and closes issues/milestones, pushes release branches, creates and merges the release-sync PR, dispatches build.yml, and creates GitHub releases so release: published can start downstream workflows. The automatic GITHUB_TOKEN cannot reliably trigger those subsequent workflows.

Grant the token access only to the OpenScreen repository with:

  • Contents: read and write.
  • Issues: read and write.
  • Pull requests: read and write.
  • Actions: read and write, for explicit build dispatch.
  • Workflows: read and write, because the pushed release branch contains .github/workflows/.
  • Metadata: read-only.

Create a fine-grained token from GitHub settings, set a finite expiry, and save it as the repository secret OPENSCREEN_RELEASE_TOKEN:

gh secret set OPENSCREEN_RELEASE_TOKEN --body "<token>" --repo getopenscreen/openscreen

Rotate it by creating the replacement with the same repository and scopes, updating the secret, verifying a non-destructive workflow/API operation, then revoking the old token. Do not revoke the previous token until the replacement is installed.

The repository's main-branch ruleset must also permit the configured maintainer/PAT flow to rebase-merge the release-sync PR with --admin; that bypass is repository configuration rather than a secret.

Apple signing and notarization

build.yml enables signing only when all of these secrets are present:

Secret Purpose
MAC_CERTIFICATE_P12 Base64-encoded Developer ID Application certificate and private key imported into a temporary keychain.
MAC_CERTIFICATE_PASSWORD Password protecting the P12 archive.
MAC_CSC_NAME Signing identity passed to electron-builder and codesign.
APPLE_ID Apple account used by notarytool.
APPLE_TEAM_ID Apple Developer team identifier.
APPLE_APP_SPECIFIC_PASSWORD App-specific password used by notarytool.

The certificate account needs Developer ID signing capability, and the Apple account/app-specific password must be able to submit notarization requests for the team. Every tag signs the DMG, notarizes, staples, and validates it, pre-releases included — that keeps RC testers out of xattr -rd com.apple.quarantine, and exercises the whole credential path on each candidate instead of first proving it on the promotion build. If any value is missing, the macOS job falls back to an ad-hoc signature and still creates a DMG.

Rotate the certificate by exporting a replacement P12, base64-encoding it without line-wrap changes, updating the P12/password/name secrets together, testing a stable-format manual build, then revoking the old certificate if required. Rotate the app-specific password in Apple ID settings, replace APPLE_APP_SPECIFIC_PASSWORD, verify notarization, and revoke the old password. APPLE_ID and APPLE_TEAM_ID normally change only when the owning account or team changes.

Microsoft Store publishing

build.yml's publish-msstore job submits the appx to the Store through the Microsoft Store Developer CLI. It runs for stable versions only, whether that comes from a pushed vX.Y.Z tag or from a manual workflow_dispatch whose release_tag is a stable one. An RC is excluded either way: it would go through certification and land on every user's machine as an automatic update.

Name Kind Purpose
MSSTORE_PRODUCT_ID Variable Store product ID (9MXQ1HQJL5G5). Gates the whole job, so a fork never publishes to our listing.
AZURE_AD_TENANT_ID Secret Entra tenant associated with the Partner Center account.
AZURE_AD_APPLICATION_CLIENT_ID Secret Application (client) ID of the Entra app registration.
AZURE_AD_APPLICATION_SECRET Secret Client secret of that registration. The only real credential here.
SELLER_ID Secret Publisher/Seller ID from Partner Center account settings.

With none of them set the job warns and skips, leaving the appx to be uploaded by hand from the run's artifacts; with some but not all it fails, on the same reasoning as the Apple path.

One-time setup, in order — each step depends on the previous one:

  1. Associate an Entra tenant with the Partner Center account.
  2. Register an application in Entra ID and create a client secret for it.
  3. In Partner Center, under Account settings → User management → Microsoft Entra applications, add that application and give it the Manager role. Tenant and client IDs alone are not enough; the failure is an authorization error at submit time.
  4. Set the four secrets and the variable.

Note what this does and does not remove. It removes the manual upload — which is worth having in itself: 1.8.0 ended up with two different packages under one version because the artifact was downloaded twice and both copies uploaded, and Partner Center rejects that outright. It does not remove certification: every submission still waits for Microsoft to validate it, and the update only goes live afterwards.

Two constraints from Microsoft's documentation: automated updates through GitHub Actions are supported for free products only, and the app must already be published and live in the Store — the API cannot create a listing, only submit to an existing one.

msstore submission updateMetadata can also drive the Store listing text from a versioned metadata.json, which would replace the CSV export/import round-trip. Not wired up here.

It has submitted nothing yet. v1.9.5 was the job's first real run — it did not exist on the v1.9.1 or v1.9.2 builds — and it failed: We could not find a project publisher for the project at …Openscreen.Setup.1.9.5.appx. Credentials were fine; the CLI reported the configuration valid and resolved the product. The call was wrong. msstore publish takes a project root as its positional argument, detects the app type there, and only then accepts a built package through --inputFile; the job passed the .appx positionally and never checked the repo out, so there was no project to detect. Fixed by adding a checkout (before the artifact download — actions/checkout cleans the workspace) and calling msstore publish . --inputFile <appx> --appId <id>.

That failure was visible only because the same release carried the fix that reports the submission's real outcome instead of the configuration's. The prior version wrote "Submitted to the Store" whenever credentials resolved, under always() — so this exact failure would have shipped as a green success.

Still unverified, and the next thing likely to break: --inputFile is documented for .msix and .msixupload, and build:win:store produces an .appx (electron-builder --win appx). Whether the CLI accepts that extension is untested.

Retrying a Store submission

publish-msstore.yml submits an already-built appx on demand: workflow_dispatch with a stable release_tag, optionally a run_id (defaults to the most recent build.yml run for that tag), and a dry_run flag.

It exists because build.yml's own job has no usable retry. Re-running the failed job replays the workflow definition frozen into the original run, so a fix landed afterwards is never picked up; and re-dispatching build.yml rebuilds every platform and re-uploads the release assets with --clobber, rewriting a published release to correct a Store submission — and, if dispatched from main rather than the tag, rewriting it with binaries built from code that release never contained. v1.9.5 hit both walls.

dry_run: true is the only safe way to test this path. It passes -nc, --noCommit, which creates the submission and leaves it in draft instead of sending it to certification. Without it — and this is what build.yml does — msstore publish commits, so a dispatch fired "just to see whether the .appx is accepted" puts a build in front of users. Validate with the dry run first; submit for real only once it comes back clean.

Rotate by issuing a new client secret on the Entra registration, updating AZURE_AD_APPLICATION_SECRET, publishing one release to confirm, then deleting the old secret. The tenant, client and seller IDs change only when the registration or account does.

Discord secrets and variables

Name Kind Used for
DISCORD_BOT_TOKEN Secret RC/stable announcements, PR forum sync, roadmap sync, and weekly leaderboard posts.
DISCORD_REVIEWER_ROLE_ID Secret Role mention used by PR-to-Discord synchronization.
DISCORD_RC_TESTING_CHANNEL_ID Variable RC announcement destination.
DISCORD_RELEASE_CHANNEL_ID Variable Stable announcement destination.
DISCORD_PR_FORUM_CHANNEL_ID Variable Forum that receives PR threads.
DISCORD_ALERT_CHANNEL_ID Variable Optional alert destination for PR sync failures.
DISCORD_ROADMAP_CHANNEL_ID Variable Channel containing the synchronized roadmap message.
DISCORD_ROADMAP_MESSAGE_ID Variable Optional explicit message override; pin discovery is otherwise used.
DISCORD_SPOTLIGHT_CHANNEL_ID Variable Weekly leaderboard destination.

The bot token comes from a Discord application authorized with the bot scope. Grant only the channel permissions each automation needs: View Channel, Send Messages, Embed Links, Create Public Threads and Send Messages in Threads for forum use, Manage Threads for forum state, and Manage Messages when roadmap pinning is required. Rotate by resetting the bot token in the Discord developer portal, updating DISCORD_BOT_TOKEN, testing a non-release post/sync, then invalidating the old token automatically through the reset. Channel and role IDs are identifiers rather than credentials; update their repository variable/secret when channels or roles are replaced.

Package registry credentials and variables

Name Kind Required access and use Rotation
HOMEBREW_TAP_TOKEN Secret Token accepted by checkout/push for the repository named by HOMEBREW_TAP_OWNER and HOMEBREW_TAP_REPO; contents write is sufficient for a dedicated tap. Create a replacement, update the secret, manually dispatch update-homebrew-cask.yml, then revoke the old token.
HOMEBREW_TAP_OWNER Variable Owner of the tap repository. Update when the tap moves.
HOMEBREW_TAP_REPO Variable Tap repository name. Update when the tap moves.
HOMEBREW_CASK_NAME Variable Cask filename/name; defaults to openscreen when unset. Update with the tap's cask rename.
WINGET_ACC_TOKEN Secret Classic PAT with public_repo and workflow, from an account that can push to getopenscreen/winget-pkgs: public_repo opens the pull request on microsoft/winget-pkgs, workflow lets komac create its branch in the fork once upstream's workflow files differ from the fork's (#757). Fine-grained PATs are not supported. publish-winget.yml checks the scopes and the push access before komac runs. Replace the token, update the secret, replay publish-winget.yml for a stable tag, then revoke the old token. Adding a scope to a classic PAT keeps its value, so that alone needs no secret update.
WINGET_IDENTIFIER Variable Package identifier passed to the WinGet action. Update only if the Store/community identifier changes.
AUR_SSH_PRIVATE_KEY Secret Private SSH key whose public key is authorized for the configured AUR package repository. Add a replacement public key to AUR, update the private-key secret, manually dispatch and verify, then remove the old AUR key.
AUR_KNOWN_HOSTS Variable Pinned aur.archlinux.org host-key lines; required because strict host checking is enabled. Replace only after independently verifying an AUR host-key change.
AUR_PACKAGE_NAME Variable AUR repository/package name and workflow gate. Update if the package is renamed.

Homebrew publishing does not complete yet, and now says so. update-homebrew-cask.yml has never published a cask — not once since it was written for the v1.5.0 pipeline. Neither HOMEBREW_TAP_OWNER nor HOMEBREW_TAP_REPO has ever existed on this repository, both sat in the job-level if, and an unconfigured job resolves to skipped, which is green: every release run reads as a success. The same failure as WinGet below, found the same way and fixed the same way — the configuration test now lives in a step that names what is missing (#335). Three things are needed, and the third is the one a variable cannot supply: HOMEBREW_TAP_OWNER and HOMEBREW_TAP_REPO; the HOMEBREW_TAP_TOKEN secret with contents write on that repository; and the tap repository itself, which must be named homebrew-<something> — that prefix is how brew tap resolves a repository at all, so getopenscreen/openscreen-tap would be checked out and pushed to successfully and still be untappable. With getopenscreen/homebrew-openscreen, the install command is brew install --cask getopenscreen/openscreen/openscreen.

Note what it would publish before turning it on: the two DMGs attached to the release — signed, notarized and stapled when the Apple credentials above are complete, ad-hoc-signed and un-notarized when they are not. A cask does not change either state, because brew install --cask runs the same Gatekeeper path as a manual download: on the ad-hoc artifact users still need to strip the quarantine flag by hand (xattr -rd com.apple.quarantine). The README no longer documents that step, because every build since 1.9.0 is notarized and does not need it — so an ad-hoc release would strand users with no written way out. What the tap buys is discovery and brew upgrade, not trust.

WinGet publishing is set up, and now names what blocks it. publish-winget.yml starts on every stable release. Two prerequisites are configuration, and a ::warning:: names whichever is missing: WINGET_IDENTIFIER (OpenScreen.OpenScreen) and WINGET_ACC_TOKEN, a classic PAT with public_repo and workflow, since winget-releaser does not support fine-grained ones. The other two are in place: the fork getopenscreen/winget-pkgs, which the workflow passes as fork-user and where komac creates its branch; and a version already merged into winget-pkgs, because the action writes each manifest from the previous one and refuses to author the first — 1.9.2 went in by hand, via wingetcreate (microsoft/winget-pkgs#415902). The job used to skip in silence when unconfigured: the test sat in the job-level if, a skipped job is green, and eight releases in a row reported success while publishing nothing, which is how #148 stayed open without anyone noticing.

Why workflow, which neither winget-releaser nor komac documents (#757). The workflow published 1.9.6 and 1.10.0, then failed on every stable release from 1.11.0 to 1.13.0 with <account> does not have the correct permissions to execute CreateRef — same komac 2.16.0, same fork, the account an admin of it. komac creates its branch in the fork at the tip of upstream master, and GitHub lets a PAT without workflow create that ref only if every workflow file there already exists, same path and contents, on some branch of the fork. That held while upstream's workflows matched the fork's, as they did at both successes. It stopped on 2026-08-26, when microsoft/winget-pkgs began editing .github/workflows/ (nine commits in the next three weeks); the fork, last synced 2026-08-11, has differed ever since. A read-only step now checks the token's classic scopes, its push access to the fork, and — only while the fork's workflows differ from upstream's — workflow, and fails naming the missing one before komac runs. Sync fork on getopenscreen/winget-pkgs also unblocks a release without the scope, but only until upstream edits a workflow again.

workflow is not free: it lets the token rewrite workflow files in every repository its owner can push to, this one included, and the job hands the token to code it does not pin — the action installs cargo-bins/cargo-binstall@main and the latest komac at run time. A machine account that owns its own winget-pkgs fork and holds no role in getopenscreen bounds that; FORK_OWNER in the workflow is the line to change.

Note what it publishes: winget-releaser submits the NSIS .exe attached to the release to the community repository, and that installer is unsigned. Users who install through the Microsoft Store, or through winget --source msstore, get the Store package that Microsoft signs during certification instead. Publishing to the community source therefore adds a second, unsigned route alongside the signed one. komac also hashes that .exe the moment the release is published, so the asset must not be replaced afterwards: 1.10.0's was, by a rebuild from release/v1.10.0 52 minutes after the submission, and winget install failed on the hash until a community member corrected the manifest (microsoft/winget-pkgs#423711).

Automatic GITHUB_TOKEN

GitHub supplies GITHUB_TOKEN per run. Workflows use it for semantic PR validation, release-asset reads, issue bookkeeping, and the Nix bump PR. Its scopes come from each workflow's permissions block and it is not manually created or rotated. Do not replace it with a PAT unless cross-workflow triggering or external-repository access is actually required.

Secret-handling rules

  • Store credentials as repository or environment secrets, never repository variables or committed files.
  • Keep non-sensitive channel IDs, package IDs, repository names, and known-host material in variables.
  • Scope tokens to the single repository or external package destination they need.
  • Rotate before expiry and verify the replacement before revoking the previous credential.
  • Treat workflow logs and manual shell commands as public: pass values through secret inputs/environment variables and never echo them.