From 30a9989a72fe64f2dccf2289f1173a4476985f5e Mon Sep 17 00:00:00 2001 From: Vdevers Date: Sun, 27 Sep 2026 21:47:50 -0400 Subject: [PATCH] Say when the release actually stops for approval MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RELEASING.md said the workflow waits for approval before pushing. It waits before starting: the job runs inside the nuget environment, so GitHub holds it at step zero. Approving means "start this release", not "these packages look right" — nothing is built, tested or packed until it happens, and once it does the job runs to the end without stopping again. That is still worth having, because a tag pushed by accident publishes nothing on its own. But it is not the review the document described, and the difference decides whether the gate is any use: seeing the packages before deciding needs the job split in two, with only the pushing half in the environment. That is written down now rather than left to be discovered. NUGET_USER is named rather than described, because describing it was not enough. It is the nuget.org account that created the policy, which is not always the one that owns the packages, and nuget.org says exactly that in the error when it is wrong. The 401 it fails with is now in the recovery list, along with the part that matters: the tag does not need to move, re-running the failed job is enough. --- .github/workflows/release.yml | 10 ++++++-- CHANGELOG.md | 13 +++++++++++ RELEASING.md | 44 +++++++++++++++++++++++++---------- 3 files changed, 53 insertions(+), 14 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c70b561..c30231b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,8 +1,14 @@ name: Release # Publishing to NuGet cannot be undone: a version can be delisted but never replaced. So the tag -# does not publish on its own. The whole suite runs again here, on the exact commit being shipped, -# and the push waits on the `nuget` environment, which is where a required reviewer belongs. +# does not publish on its own. The job runs inside the `nuget` environment, which means GitHub +# holds it before the first step until a reviewer approves: a tag pushed by accident builds +# nothing and publishes nothing. +# +# Approving starts the release rather than signing off on its output — once it runs, the whole +# suite runs again on the exact commit being shipped and the push follows without stopping. To +# review the built packages before they go out, this would have to be two jobs with only the +# second one in the environment. # # There is no NuGet API key stored in this repository. The job proves who it is with a token # GitHub signs for this workflow, in this repository, in this environment, and nuget.org hands back diff --git a/CHANGELOG.md b/CHANGELOG.md index da003b7..c04434f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,19 @@ Before v1.0, a minor version may introduce breaking changes. ## [Unreleased] +### Documentation + +- `RELEASING.md` said the release workflow waits for approval before pushing. It waits before + starting: the whole job runs inside the `nuget` environment, so GitHub holds it at step zero. + Approving means "start this release", not "these packages look right", and nothing is built + until it happens. Worth having either way — a tag pushed by accident publishes nothing — but + not what was written, and the difference decides whether the gate is any use to you. +- The value of `NUGET_USER` is named rather than described. It is the nuget.org account that + created the trusted publishing policy, and where that differs from the account that owns the + packages it is the creator that counts. Getting it wrong costs a full release run: everything + passes and the token exchange fails with a 401 one step before the push, which is now in the + list of things that go wrong and how to recover from them. + ### Added - The source generator matches members the way the run-time engine does, by spelling out a path: diff --git a/RELEASING.md b/RELEASING.md index aa7116b..4411c0f 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -24,15 +24,27 @@ repository, in this environment, and nuget.org hands back a key that lasts an ho The workflow file name and the environment are part of what nuget.org checks, so renaming either one stops publishing until the policy is updated to match. That is the point of them. -2. Add the nuget.org **profile name** (not the email address) as the repository secret - `NUGET_USER`, under *Settings → Secrets and variables → Actions*. It is not sensitive, but - keeping it out of a public file is what NuGet recommends, and the workflow stops with a clear - message when it is missing. +2. Add the nuget.org **profile name** as the repository secret `NUGET_USER`, under + *Settings → Secrets and variables → Actions*. Today that value is `vdevers`. It is the + nuget.org account name, not the email address and not the GitHub one, and where the two + differ it is the account that **created** the policy rather than the one that owns the + packages — nuget.org says so in the error when it is wrong. It is not sensitive, but keeping + it out of a public file is what NuGet recommends, and the workflow stops with a clear message + when it is missing. -3. Open *Settings → Environments → nuget* and add yourself as a required reviewer. The release - workflow waits there before pushing, which is the last chance to stop a release that should not - go out. The environment is created by the first run if it does not exist, but without a - reviewer it does not stop anything. +3. Open *Settings → Environments → nuget* and add yourself as a required reviewer. + + Be clear about what that gate is. The whole job runs inside the environment, so GitHub holds + it **before it starts**: approving means "start this release", not "these packages look + right". Nothing is built, tested or packed until you approve, and once you do, the job runs + to the end and pushes without stopping again. + + That is still the thing worth having — a tag pushed by accident does not publish anything on + its own — but if what you want is to see the packages and then decide, the job has to be split + in two, with only the pushing half in the environment. + + The environment is created by the first run if it does not exist, but without a reviewer it + does not stop anything. On a private repository a new policy is only provisionally active for seven days and lapses if nothing is published in that time. This repository is public, so that does not apply, but it is @@ -49,10 +61,12 @@ worth knowing if the repository is ever made private. git push origin v0.8.0-preview.1 ``` -3. The `Release` workflow builds, runs the whole suite on the tagged commit, publishes the - ahead-of-time sample natively and runs it, runs the pilot application, packs the four - packages and waits for approval. -4. Approve it. The packages go to NuGet and a GitHub release is created with them attached. +3. The `Release` workflow waits for your approval before doing anything, because the job runs + inside the `nuget` environment. Approve it from the run page: **Review deployments → + nuget → Approve and deploy**. +4. It then builds, runs the whole suite on the tagged commit, publishes the ahead-of-time sample + natively and runs it, runs the pilot application, packs the four packages, pushes them to + NuGet and creates a GitHub release with them attached. It does not stop again. The version comes from the tag, so nothing needs editing to release. `VersionPrefix` in `Directory.Build.props` only names the builds made in between. @@ -65,6 +79,12 @@ The version comes from the tag, so nothing needs editing to release. `VersionPre - **A package failed to push and others went up.** Re-run the job. The push uses `--skip-duplicate`, so what is already on NuGet is left alone. The key is asked for again on the re-run, since each one lasts only an hour. +- **The token exchange fails with HTTP 401**, saying no matching trust policy was found for the + user. `NUGET_USER` does not name the nuget.org account that created the policy. This has + happened: the secret held a name that was not the nuget.org one, everything else passed, and + the job died one step before pushing. Fix the secret and use **Re-run failed jobs** on the same + run — the tag does not need to move, and the NuGet key is asked for again because each one + lasts an hour. - **The push is rejected as unauthorized.** The policy on nuget.org no longer matches the job: check the workflow file name, the environment name and the package owner against the table above. - **A version went out that should not have.** It cannot be taken back. Delist it on nuget.org so