From 5aeae6e27e9578436dd6de8e039df714ca520bef Mon Sep 17 00:00:00 2001 From: Jens Geyer Date: Sun, 20 Sep 2026 23:25:17 +0200 Subject: [PATCH] THRIFT-6327: Document the credentials the release workflows need in one place Client: build Six workflows publish something when a GitHub release is published: pypi.yml, release_ruby.yml, release_rust.yml, dotnet-tool.yml, winget.yml and chocolatey.yml. Between them they need one repository variable, two repository secrets and four trusted publishing policies on the receiving side. Every one of those was documented, and no two of them in the same place: CHOCO_API_KEY inside the Chocolatey prose, WINGET_TOKEN inside the WinGet prose, the NuGet policy and NUGET_USER inside a bullet under Third Party Package Managers, the PyPI policy inside another bullet, and the crates.io and RubyGems ones nowhere at all. A release manager preparing their first release had no way to find out what has to be set up other than reading the whole document. ReleaseManagement.md gains a Release Automation Credentials section listing each one: what it is, whether it is a secret or a variable, which workflow consumes it, and what happens when it is missing. The per package prose stays where it is; the new section links into it rather than repeating it. Three things worth having written down, because none of them is visible from the outside: Four of the six hold no stored credential at all. PyPI, RubyGems, crates.io and NuGet publish over trusted publishing, exchanging the run's OIDC token for a short lived key, so what has to exist is a policy naming this repository, the workflow file and the release environment. Only WinGet and Chocolatey use a stored secret, because neither has an OIDC path. WINGET_TOKEN has to be a classic personal access token. Fine grained tokens are not supported by wingetcreate. A green run does not prove anything was published. The WinGet and Chocolatey steps deliberately do not fail when their secret is absent: they build and upload the artifact, emit a warning and print how to publish by hand in the run summary. That keeps a missing secret from failing a release, but it means the summary is what to read, not the tick. Co-Authored-By: Claude Opus 5 (1M context) --- doc/ReleaseManagement.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/doc/ReleaseManagement.md b/doc/ReleaseManagement.md index a269a0b806d..c30e7f6113b 100644 --- a/doc/ReleaseManagement.md +++ b/doc/ReleaseManagement.md @@ -425,6 +425,45 @@ Voting on the development mailing list provides additional benefits (wisdom from 1. Make an announcement on the dev@ and user@ mailing lists of the release. There's no template to follow, but you can point folks to the official web site at https://thrift.apache.org, and to the GitHub site at https://github.org/apache.thrift. +### Release Automation Credentials + +Six workflows publish something when a GitHub release is published. What each +of them needs is described where that package is described, further down; this +is the list, so that it can be checked before a release rather than discovered +during one. + +Most of it needs no stored credential. PyPI, RubyGems, crates.io and NuGet are +all published over **trusted publishing**: the workflow exchanges the run's OIDC +token for a short-lived key, so nothing is kept in the repository. What has to +exist is a policy on the receiving side naming this repository, the workflow +file and the `release` environment. + +| Needed | Kind | Used by | Without it | +|---|---|---|---| +| PyPI trusted publisher for `.github/workflows/pypi.yml` | policy on pypi.org | `pypi.yml` | the publish step fails | +| crates.io trusted publisher for `.github/workflows/release_rust.yml` | policy on crates.io | `release_rust.yml` | the publish step fails | +| RubyGems trusted publisher for `.github/workflows/release_ruby.yml` | policy on rubygems.org | `release_ruby.yml` | the publish step fails | +| NuGet trusted publisher for `.github/workflows/dotnet-tool.yml` | policy on nuget.org | `dotnet-tool.yml` | the publish step fails | +| `NUGET_USER` | repository **variable** | `dotnet-tool.yml` | the publish step fails | +| `WINGET_TOKEN` | repository **secret** | `winget.yml` | nothing is submitted; see below | +| `CHOCO_API_KEY` | repository **secret** | `chocolatey.yml` | nothing is pushed; see below | + +All of them are scoped to the `release` [environment](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments). +`GITHUB_TOKEN` is provided by Actions itself and needs no setup. + +Two notes that are easy to get wrong: + +* **`WINGET_TOKEN` has to be a _classic_ personal access token** with the + `public_repo` scope. Fine-grained tokens are not supported by `wingetcreate`. +* **A green run does not prove anything was published.** The WinGet and + Chocolatey steps deliberately do *not* fail when their secret is missing: they + build and upload the artifact, emit a warning, and print in the run summary how + to publish by hand. That keeps a missing secret from failing a release, but it + means the run summary is what to read, not the tick. + +`CHOCO_API_KEY` is expected to be missing for now - see +[Chocolatey](#chocolatey) below, the package id has not been handed over yet. + ### Post-Release 1. Visit https://reporter.apache.org/addrelease.html?thrift and register it. You will get an automated reminder as the one who committed into dist. This informs the Apache Board of Directors of releases through project reports.