Technology
NuGet.org Staged Publishing: Adding a Human Release Gate to .NET Package Pipelines
On November 17, 2026, Microsoft introduced staged publishing on NuGet.org, allowing .NET pipelines using the .NET 11 RC2 SDK to upload and validate packages privately without making them public. Staged packages remain invisible to search and restore until an authorized maintainer promotes them on NuGet.org. Learn how staging groups, staging-only API keys, and Trusted Publishing harden your release boundary—plus the key limits to plan around.
8 min read
NuGet.org Staged Publishing: Adding a Human Release Gate to .NET Package Pipelines
Executive Summary
On November 17, 2026, Microsoft introduced staged publishing on NuGet.org, now available to all package publishers. In a conventional .NET CI/CD pipeline, dotnet nuget push immediately triggers public publication: the same credential that uploads the .nupkg artifact also makes it live to every downstream consumer. Staged publishing splits that authority by letting automation upload packages for full NuGet.org validation—including malware scanning, signature checks, and repository signing—while keeping them completely private until an authorized maintainer explicitly promotes them through the NuGet.org website.
Combined with staging-only API keys (or NuGet Trusted Publishing policies scoped strictly to staging) and staging groups for multi-package releases, staged publishing creates a practical human release gate for coordinated security fixes, multi-library .NET releases, and agent-assisted maintenance PRs.
Confidence & Evidence Caveats: Confidence in the workflow, .NET 11 RC2 CLI syntax, and security boundaries is high based on the primary Microsoft .NET Blog announcement (November 17, 2026), corroborated by WindowsForum (November 17, 2026) and hands-on pipeline testing by Mikhail Petrusheuski (November 18, 2026). Note four explicit limitations documented by Microsoft: (1) staged publishing does not provide a private restore feed (even for the package owner); (2) group promotion is not atomic, so related packages can become restorable at different times; (3) promotion requires a two-factor-authenticated account session, not a fresh per-promotion 2FA challenge; and (4) staged content expires if unpromoted, though Microsoft has not published the exact retention window.
Technical Mechanics and Architecture
Splitting Build Preparation from Public Publication
Staged publishing is opt-in, leaving existing dotnet nuget push workflows unchanged. When a publisher uploads via the NuGet.org web UI (selecting Staging under Publishing Mode) or via the .NET 11 RC2 CLI (dotnet package stage push), NuGet.org runs its standard validation pipeline:
- Malware scanning
- Author/package signature verification
- NuGet.org repository signing
Once validation passes, the package enters a ready-for-promotion state. Unlike an unlisted package—which is hidden from search results yet still restorable by anyone who knows its exact package ID and version—a staged package is absent from public package pages, search indices, and restore endpoints altogether.
+-----------------------------------------------------------------------+
| CI/CD Pipeline (.NET 11 RC2 SDK) |
| - Build, test, and verify restore against local/private feed |
| - Auth: Staging-only API key OR Trusted Publishing (1-hr OIDC token) |
| - Command: dotnet package stage push ... --group <release-id> |
+-----------------------------------+-----------------------------------+
|
v
+-----------------------------------------------------------------------+
| NuGet.org Validation & Staging Gate |
| - Runs malware scan, signature checks, and repository signing |
| - Hidden from search, package pages, and ALL restore operations |
| - Organized under Staging Owner (User or Org); expires if unpromoted |
+-----------------------------------+-----------------------------------+
|
(Human Review & "Promote" / "Promote group"
on NuGet.org Website with 2FA-enabled session)
|
v
+-----------------------------------------------------------------------+
| Public NuGet.org Distribution Pipeline |
| - Packages enter public feed independently (non-atomic for groups) |
| - Maintainer verifies public restore before release announcement |
+-----------------------------------------------------------------------+
Safe CI/CD Staging Workflow (.NET 11 RC2)
Because dotnet package stage push was introduced in the .NET 11 RC2 SDK (older .NET 10 SDKs do not recognize the stage subcommand), pin .NET 11 in your release workflow and test packages against a local folder feed before staging them on NuGet.org. Never store $NUGET_API_KEY in source control, and scope the credential to staging-only so a compromised CI runner cannot push directly to consumers:
# 1. Verify restore from a local artifact feed in a clean consumer project first
# (Staging on NuGet.org is NOT a private restore feed)
# 2. Stage a package into a named staging group using a staging-only credential
dotnet package stage push ./artifacts/Contoso.Library.1.2.0.nupkg \
--source https://api.nuget.org/v3/index.json \
--api-key "$NUGET_STAGING_API_KEY" \
--group november-release
If the specified --group ID does not exist yet, NuGet.org creates it automatically under the staging owner. Note that Microsoft also shared roadmap examples for future CLI subcommands (dotnet package stage list, dotnet package stage group create, dotnet package stage group list, dotnet package stage group add), but explicitly noted these are not final syntax and that promotion remains a website-only action (no CLI approval command is planned for now, though Microsoft's Jon Douglas noted in blog comments that commit/rollback design feedback is welcome on NuGet/Home).
Evidence: Publishing Modes, Security Boundaries, and Operational Limits
Comparison: Standard Push vs. Unlisted vs. Staged Publishing
| Capability / Behavior | Standard dotnet nuget push |
Unlisted Package | Staged Publishing (dotnet package stage push) |
|---|---|---|---|
| Runs NuGet.org Validation | Yes (malware, signature, repo signing) | Yes | Yes |
| Visible in Search & Package Pages | Yes | No | No |
| Restorable by Exact Version | Yes (public immediately) | Yes (anyone with exact ID + version) | No (blocked even for owner until promoted) |
| Pipeline Credential Scope | Can publish directly to consumers | Can publish directly to consumers | Can restrict to staging-only API key or OIDC policy |
| Multi-Package Coordination | Independent pushes | Independent pushes | Staging groups (review together, promote in one click) |
| Atomic Group Availability | N/A | N/A | No (packages distribute independently after promotion) |
Key Operational & Security Facts
- Two-Factor Authentication & Session Scope: Promoting a single package (
Promote) or group (Promote group) requires an authorized maintainer signed into NuGet.org with 2FA enabled. However, Microsoft explicitly clarifies that this is a human-presence checkpoint within an authenticated session—not a fresh per-promotion 2FA step-up challenge. - Trusted Publishing Synergy: Microsoft recommends pairing staged publishing with NuGet Trusted Publishing (which exchanges short-lived OIDC tokens from CI/CD systems like GitHub Actions for temporary, single-use, 1-hour API keys) and restricting that Trusted Publishing policy to staging-only. While an attacker who compromises the CI pipeline could still upload a malicious artifact into staging, they cannot make it public without compromising an authorized maintainer's NuGet.org session.
- Staging Owner Permissions: Permissions follow the staging owner (either an individual user or a NuGet.org organization). Being a co-owner of a package does not automatically grant visibility into content staged on behalf of a different owner—an important detail to test before a coordinated security embargo.
- Non-Atomic Group Promotion: As demonstrated in Mikhail Petrusheuski's testing, if
Extensionsdepends onCore >= 1.2.0andExtensionsfinishes public distribution beforeCore, early consumers can hitNU1101restore errors during the propagation window.
Hardening Playbook & Rollout Checklist
Six-Step Adoption Playbook
- Test Against a Local or Private Feed First: Because staged packages cannot be restored from NuGet.org, prove in CI that every
.nupkgin your release set installs cleanly from a local directory feed with package source mapping enabled. - Issue Staging-Only Credentials (or OIDC Policies): Replace broad push keys in CI/CD with a staging-only API key—or better, a NuGet Trusted Publishing policy restricted to staging-only—so pipeline compromises cannot publish directly to users.
- Standardize on Organization-Owned Staging Groups: Stage multi-package releases under an organization staging owner rather than an individual developer account so co-maintainers do not lose access during a release or embargo.
- Enforce a Pre-Promotion Maintainer Checklist: Before clicking Promote or Promote group, verify package IDs, versions, all validation statuses, local-feed test evidence, dependency version ranges, and source-commit metadata.
- Check
.snupkgSymbol Package Behavior in Staging: Verify how symbol packages are handled on your first staged release rather than assuming.snupkgartifacts follow.nupkgentries automatically. - Poll Public Flat-Container Endpoints Before Announcing: After clicking Promote group, monitor each package's promotion status on NuGet.org and verify that all packages in the dependency graph are restorable before publishing release notes or security advisories.
Defensive Verification & Polling Checks
Use these read-only checks to confirm your SDK supports staging and to verify public availability after group promotion before announcing a release:
# 1. Verify .NET SDK version supports `dotnet package stage push` (.NET 11 RC2+)
dotnet --version
# 2. Poll NuGet.org flat-container index for a promoted package version before announcing
curl -fsSL "https://api.nuget.org/v3-flatcontainer/contoso.library/index.json" | grep -F '"1.2.0"'
Rollback & Remediation Notes
If you discover a defect or unexpected artifact while a package is still staged, do not promote it—upload a corrected version or investigate the pipeline immediately (note that Microsoft's announcement does not document a manual discard button, and unpromoted staged content expires automatically). If a defect is discovered after promotion, follow standard NuGet remediation: unlist the affected version on NuGet.org to hide it from search/new adoption, publish a patched x.y.(z+1) version through staging, and rotate any compromised CI credentials.
Frequently Asked Questions
1. Can I restore a staged package from NuGet.org to test it before promoting? No. Microsoft explicitly states that staged publishing does not provide a private restore feed, even for the package owner. Test your packages against a local folder feed or private registry first, then stage the verified artifacts on NuGet.org.
2. Which .NET SDK version is required for dotnet package stage push?
Basic CLI staging (dotnet package stage push) requires the .NET 11 RC2 SDK or newer. Older SDKs (such as .NET 10) do not include the stage command.
3. How is a staged package different from an unlisted package? An unlisted package is hidden from search results, but anyone who knows its exact package ID and version can still restore it. A staged package is completely unavailable to search, package pages, and all restore operations until promoted.
4. Is promoting a staging group atomic? No. When you click Promote group, each package moves through NuGet.org's public distribution pipeline independently and may become restorable at slightly different times. Wait until all dependent packages are publicly restorable before announcing the release.
5. Does NuGet.org require a fresh 2FA prompt for every package promotion? No. Promotion requires an authorized user signed in with 2FA enabled on their account, which acts as a human-presence checkpoint in an authenticated session rather than a per-promotion step-up 2FA challenge.
Sources
- Microsoft .NET Blog (Primary) — Introducing staged publishing on NuGet.org (Published November 17, 2026)
- WindowsForum (Secondary) — NuGet.org Staged Publishing Adds Human Approval for Package Releases (Published November 17, 2026)
- Mikhail Petrusheuski / Medium (Secondary) — NuGet.org Just Added a Human Release Gate for .NET Packages (Published November 18, 2026)