Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
44 changes: 32 additions & 12 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down
Loading