Skip to content

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

ci(winget): name the missing token scope before komac's CreateRef fails

Etienne Lescotf5f6e7ba3220
diff --git a/.github/workflows/publish-winget.yml b/.github/workflows/publish-winget.yml
index 13f109753..b5fe70039 100644
--- a/.github/workflows/publish-winget.yml
+++ b/.github/workflows/publish-winget.yml
@@ -30,17 +30,84 @@ jobs:
# au niveau de l'étape — seul `env` l'est. D'où ce booléen-en-chaîne, qui expose
# la présence du token sans jamais exposer sa valeur.
HAS_TOKEN: ${{ secrets.WINGET_ACC_TOKEN != '' }}
+ # La fork de winget-pkgs où komac crée sa branche — getopenscreen/winget-pkgs,
+ # celle qui a publié 1.9.6 et 1.10.0. C'est déjà la valeur par défaut de
+ # `fork-user`, mais écrite ici elle est partagée : le contrôle ci-dessous vise
+ # la fork même où komac écrira, pas une supposition.
+ FORK_OWNER: ${{ github.repository_owner }}
steps:
- # Les deux pièges nommés ici sont documentés chez l'action et coûteraient chacun
- # une release pour être découverts : un PAT fine-grained N'EST PAS supporté
- # (vedantmgoyal9/winget-releaser#172), et l'action refuse de tourner tant qu'aucune
- # version du paquet n'existe déjà dans winget-pkgs — elle part d'un manifeste
- # existant pour écrire le suivant. La première soumission est donc manuelle,
- # `wingetcreate new`, et l'automatisation ne prend le relais qu'ensuite.
+ # N'annonce que ce que cette étape teste — la variable et le secret — et ce que ce
+ # secret doit être. Un PAT fine-grained N'EST PAS supporté
+ # (vedantmgoyal9/winget-releaser#172) : komac sait committer avec, pas ouvrir la
+ # PR sur microsoft/winget-pkgs. Les deux autres prérequis sont en place et vérifiés
+ # ailleurs : la fork par l'étape suivante, et l'existence d'une première version
+ # dans winget-pkgs par l'action elle-même, qui part d'un manifeste existant pour
+ # écrire le suivant — 1.9.2 y est entrée à la main, via `wingetcreate`.
- name: Report that winget publishing is not configured
if: env.IDENTIFIER == '' || env.HAS_TOKEN != 'true'
run: |
- echo "::warning title=winget publishing skipped::Nothing was published to winget. Needs (1) the repository variable WINGET_IDENTIFIER, currently ${{ env.IDENTIFIER == '' && 'UNSET' || 'set' }}; (2) the secret WINGET_ACC_TOKEN, currently ${{ env.HAS_TOKEN == 'true' && 'set' || 'UNSET' }} — a CLASSIC PAT with public_repo scope, fine-grained tokens are not supported; (3) a fork of microsoft/winget-pkgs under getopenscreen; and (4) at least one version of the package already merged into winget-pkgs, since this action updates an existing manifest and refuses to create the first one. See https://github.com/getopenscreen/openscreen/issues/148"
+ echo "::warning title=winget publishing skipped::Nothing was published to winget. Needs (1) the repository variable WINGET_IDENTIFIER, currently ${{ env.IDENTIFIER == '' && 'UNSET' || 'set' }}; and (2) the secret WINGET_ACC_TOKEN, currently ${{ env.HAS_TOKEN == 'true' && 'set' || 'UNSET' }} — a CLASSIC PAT with the public_repo and workflow scopes, from an account that can push to ${{ env.FORK_OWNER }}/winget-pkgs; fine-grained tokens are not supported. See technical-documentation/engineering/release-and-secrets.md and https://github.com/getopenscreen/openscreen/issues/757"
+
+ # Le piège qui a coûté 1.11.0 à 1.13.0 (#757), et que ni l'action ni komac ne
+ # documentent : komac crée sa branche dans la fork à la pointe du master
+ # d'upstream, et GitHub refuse cette ref à un PAT sans le scope `workflow` dès
+ # qu'elle porte un fichier de .github/workflows qu'aucune branche de la fork n'a
+ # à l'identique. Upstream retouche ses workflows depuis le 26/08 — neuf commits
+ # en trois semaines — et la fork ne se resynchronise jamais seule. komac n'en dit
+ # que « does not have the correct permissions to execute CreateRef », qui accuse
+ # le compte, pourtant admin de la fork, au lieu du scope qui manque.
+ #
+ # D'où ce contrôle, en lecture seule, avant komac : les scopes classiques du
+ # token (l'en-tête X-OAuth-Scopes, qu'un PAT fine-grained ne porte pas), son
+ # droit de push sur la fork, puis `workflow` — exigé seulement si les workflows
+ # de la fork divergent de ceux d'upstream, puisqu'un « Sync fork » manuel suffit
+ # alors, jusqu'à la retouche suivante.
+ - name: Check that WINGET_ACC_TOKEN can create komac's branch in the fork
+ if: env.IDENTIFIER != '' && env.HAS_TOKEN == 'true'
+ shell: bash
+ env:
+ GH_TOKEN: ${{ secrets.WINGET_ACC_TOKEN }}
+ run: |
+ set -euo pipefail
+ fork="$FORK_OWNER/winget-pkgs"
+ fail() {
+ echo "::error title=WINGET_ACC_TOKEN cannot publish::$1"
+ exit 1
+ }
+
+ if ! response=$(gh api --include user 2>&1); then
+ fail "GitHub rejected WINGET_ACC_TOKEN: $(tail -n 1 <<< "$response")"
+ fi
+ # Le nom de l'en-tête seul est retiré : les scopes eux-mêmes contiennent des
+ # « : » (read:org, repo:status), et un découpage sur « : » lirait repo:status
+ # comme repo.
+ scopes=$(tr -d '\r' <<< "$response" | awk 'tolower($0) ~ /^x-oauth-scopes:/ { sub(/^[^:]*:[ \t]*/, ""); print }')
+ scopes=${scopes// /}
+ echo "WINGET_ACC_TOKEN classic scopes: ${scopes:-none}"
+ if [[ ",$scopes," != *,public_repo,* && ",$scopes," != *,repo,* ]]; then
+ fail "WINGET_ACC_TOKEN lacks the public_repo scope (classic scopes: ${scopes:-none}). It must be a classic PAT with public_repo to open the pull request on microsoft/winget-pkgs; a fine-grained PAT carries no classic scopes and is not supported."
+ fi
+
+ if ! push=$(gh api "repos/$fork" --jq '.permissions.push' 2>&1); then
+ fail "WINGET_ACC_TOKEN cannot read $fork, the fork komac creates its branch in: $(tail -n 1 <<< "$push")"
+ fi
+ if [[ "$push" != true ]]; then
+ fail "The account behind WINGET_ACC_TOKEN has no push access to $fork, the fork komac creates its branch in."
+ fi
+
+ if [[ ",$scopes," == *,workflow,* ]]; then
+ echo "OK: public_repo and workflow scopes, push access to $fork."
+ exit 0
+ fi
+ workflows_tree() {
+ gh api "repos/$1/contents/.github?ref=master" --jq '.[] | select(.name == "workflows") | .sha'
+ }
+ upstream=$(workflows_tree microsoft/winget-pkgs)
+ ours=$(workflows_tree "$fork")
+ if [[ "$upstream" != "$ours" ]]; then
+ fail "WINGET_ACC_TOKEN lacks the workflow scope, and $fork is behind microsoft/winget-pkgs on .github/workflows. komac creates its branch at upstream master, and GitHub refuses that ref to a PAT without workflow; komac reports it as 'does not have the correct permissions to execute CreateRef' (#757). Add the workflow scope to this classic PAT at https://github.com/settings/tokens (its value does not change, so the secret stays as is), or press Sync fork on https://github.com/$fork, which only holds until upstream edits a workflow again."
+ fi
+ echo "OK: public_repo scope, push access to $fork, and its .github/workflows match upstream's, so this run does not need the workflow scope."
# Épinglé sur le SHA de v2 : un tag git est mutable, et cette action tierce
# reçoit WINGET_ACC_TOKEN. Un tag repointé suffirait à exfiltrer le token
@@ -55,3 +122,4 @@ jobs:
installers-regex: 'Setup\..*\.exe$'
release-tag: ${{ inputs.tag || github.event.release.tag_name }}
token: ${{ secrets.WINGET_ACC_TOKEN }}
+ fork-user: ${{ env.FORK_OWNER }}
diff --git a/technical-documentation/engineering/ci-workflows.md b/technical-documentation/engineering/ci-workflows.md
index ba52a2cdc..95d5082d4 100644
--- a/technical-documentation/engineering/ci-workflows.md
+++ b/technical-documentation/engineering/ci-workflows.md
@@ -124,7 +124,7 @@ At a high level, the RC workflow creates or reuses `release/vX.Y.Z`, tags its ti
These workflows run for stable published releases and support manual replay with a tag:
- `update-homebrew-cask.yml` waits for both macOS DMGs, hashes them, writes a cask, and pushes to the configured tap. Manual replay refuses any tag that is not a stable `vMAJOR.MINOR.PATCH`, because `workflow_dispatch` takes free text and the `prerelease` filter only covers the `release` event.
-- `publish-winget.yml` passes the matching NSIS release asset to `winget-releaser`.
+- `publish-winget.yml` passes the matching NSIS release asset to `winget-releaser`, after a read-only step checks that the token can create komac's branch in the `winget-pkgs` fork (#757).
- `bump-nix-package.yml` computes `npmDepsHash`, updates `nix/package.nix`, and opens a PR.
- `aur-publish.yml` hashes the pacman release asset, updates `PKGBUILD` and `.SRCINFO`, and pushes over SSH.
diff --git a/technical-documentation/engineering/release-and-secrets.md b/technical-documentation/engineering/release-and-secrets.md
index 0e794959f..0895b98b2 100644
--- a/technical-documentation/engineering/release-and-secrets.md
+++ b/technical-documentation/engineering/release-and-secrets.md
@@ -211,7 +211,7 @@ The bot token comes from a Discord application authorized with the `bot` scope.
| `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 | Token consumed by `winget-releaser` to submit to the WinGet community repository; grant the scopes required by that action's upstream submission account and no unrelated repository access. | Replace the token, update the secret, replay `publish-winget.yml` for a stable tag, then revoke the old token. |
+| `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. |
@@ -223,9 +223,13 @@ The bot token comes from a Discord application authorized with the `bot` scope.
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 does not complete yet, and now says so.** `publish-winget.yml` starts on every stable release; whether it publishes depends on four prerequisites, and it names the missing ones in a `::warning::` instead of passing quietly. It used to pass quietly: the configuration test sat in the job-level `if`, an unconfigured job resolved to `skipped`, and a skipped job is green — so eight releases in a row reported success while publishing nothing, which is how #148 stayed open without anyone noticing. The four are: `WINGET_IDENTIFIER` (set, `OpenScreen.OpenScreen`); `WINGET_ACC_TOKEN` (absent — it must be a *classic* PAT with `public_repo`, since `winget-releaser` does not support fine-grained ones); a fork of `microsoft/winget-pkgs` under `getopenscreen`, which is where the action pushes its branch; and at least one version of the package already merged into `winget-pkgs`, because the action writes each manifest from the previous one and refuses to author the first. That first submission is manual, via `wingetcreate new`.
+**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.
-Note what it would publish before turning it on: `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 — worth doing deliberately rather than by flipping a variable.
+**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`