Publishing a NuGet package is easy. Making sure that package is safe to consume is a different problem.
A package can build successfully, pass unit tests, and still contain a broken API, missing dependency, incorrect package metadata, or a behavior change that affects existing applications. Once a package is published to a public feed, fixing the problem usually means publishing another version and asking consumers to upgrade.
A staged release process reduces that risk. Instead of publishing every package directly to the public feed, the package moves through controlled stages such as build, validation, internal testing, approval, and public release.
This approach works especially well for libraries shared across multiple applications or teams.
What Is a Staged NuGet Release?
A staged NuGet release separates package creation from package publication.
A typical flow looks like this:
Developer Commit
|
v
Build + Unit Tests
|
v
Create NuGet Package
|
v
Package Validation
|
v
Internal / Staging Feed
|
v
Integration Testing
|
v
Approval
|
v
Public NuGet Feed
The important part is that creating a .nupkg file does not automatically mean publishing it publicly.
The package can first be tested from a private feed. If problems are found, the package can be rejected without affecting existing consumers.
Why Direct NuGet Publishing Can Be Risky
A common pipeline looks like this:
steps:
- build
- test
- pack
- push
The problem is the final step.
If dotnet pack creates a package containing an unexpected change, the pipeline can immediately publish it.
Some problems are not visible during normal unit testing.
For example:
A public method signature may have changed.
A dependency version may be incorrect.
A package may contain unnecessary files.
A required file may be missing from the package.
Package metadata may be incomplete.
A breaking behavior change may only appear in a consuming application.
A package may work locally but fail when restored from a clean environment.
Staging gives you another validation point before consumers receive the package.
Separate Package Creation From Package Publishing
The first improvement is to make package creation and publication separate pipeline stages.
For example:
dotnet restore
dotnet build --configuration Release --no-restore
dotnet test --configuration Release --no-build
dotnet pack --configuration Release --no-build --output ./artifacts
The important part is that dotnet pack only creates the package.
It does not publish anything.
The resulting package can then be inspected:
artifacts/
MyLibrary.2.4.0.nupkg
MyLibrary.2.4.0.snupkg
A later pipeline stage can decide whether this package should be pushed to the staging feed.
Validate the Package Before Publishing
Building the project is not the same as validating the package.
You should inspect the generated .nupkg file before it reaches a feed.
A NuGet package is essentially a ZIP archive, so its contents can be inspected directly.
For example:
unzip -l ./artifacts/MyLibrary.2.4.0.nupkg
You should verify that the package contains the expected assemblies and metadata.
For a library targeting multiple frameworks, check that the expected folders exist:
lib/
net8.0/
netstandard2.0/
If the package contains unexpected files, investigate them before continuing the release.
Use a Staging Feed
A private NuGet feed provides a safe place to test the package.
The feed could be hosted using:
The important idea is that consumers can restore the package from the staging source without making the package publicly available.
For example:
dotnet nuget push ./artifacts/MyLibrary.2.4.0.nupkg \
--source staging-feed \
--api-key "$NUGET_API_KEY"
The package is now available for validation but has not yet been released publicly.
Test the Package as a Consumer
One of the most useful checks is to test the actual NuGet package from a clean project.
Do not test only against the project reference.
A project reference can hide packaging problems because the application directly sees the source project.
Instead, create a small test application and install the package:
dotnet new console -n PackageSmokeTest
cd PackageSmokeTest
dotnet add package MyLibrary \
--version 2.4.0 \
--source staging-feed
Then run the application:
dotnet run
This verifies the package from the consumer's perspective.
It can expose problems involving:
This type of smoke test is valuable because it tests the artifact that users will actually consume.
Use Versioning to Control the Release
Every staged package should have a clear version.
For example:
2.4.0
2.4.1
2.5.0
3.0.0
Do not repeatedly overwrite the same package version.
NuGet package versions are expected to be immutable once published to a repository. If a package has a problem, create a new version rather than trying to replace the existing one.
For example:
2.4.0 -> Problem discovered
2.4.1 -> Fixed package
This gives consumers a predictable package history.
Add Automated Package Validation
Package validation can be part of the CI pipeline.
A simple shell step can verify that the package was created:
PACKAGE=$(find ./artifacts -name "*.nupkg" | head -n 1)
if [ -z "$PACKAGE" ]; then
echo "NuGet package was not created."
exit 1
fi
echo "Package created: $PACKAGE"
You can also inspect the package contents:
unzip -l "$PACKAGE"
For .NET libraries, API compatibility checks are also useful when the package is consumed by existing applications.
The goal is to detect problems before the package reaches the approval stage.
Add a Human Approval Gate
Automation should handle repetitive validation. A human should still be able to control the production release when the package affects important consumers.
A pipeline can be structured like this:
Build
|
Test
|
Pack
|
Validate
|
Publish to Staging
|
Integration Tests
|
Manual Approval
|
Publish to Public Feed
The approval step gives a maintainer a chance to review:
Package version
Release notes
API changes
Test results
Dependency changes
Security checks
Integration test results
The person approving the release does not need to manually upload the package. The pipeline can perform the final push after approval.
Protect the Public NuGet API Key
The API key used for the public feed should never be stored in source code.
Avoid this:
dotnet nuget push package.nupkg \
--api-key "my-secret-key"
Instead, store the credential in the CI/CD platform's secret storage.
For example:
dotnet nuget push "$PACKAGE" \
--source "$NUGET_SOURCE" \
--api-key "$NUGET_API_KEY"
The pipeline should expose the secret only to the release stage that actually needs it.
This is especially important when the staging and production feeds use different credentials.
Example Release Pipeline Structure
A generic pipeline can be organized into four stages:
stages:
- build
- validate
- staging
- release
The build stage creates the package:
build:
script:
- dotnet restore
- dotnet build --configuration Release
- dotnet test --configuration Release
- dotnet pack --configuration Release --output artifacts
The validation stage checks the package:
validate:
script:
- dotnet nuget verify artifacts/*.nupkg
- unzip -l artifacts/*.nupkg
The staging stage publishes the package internally:
staging:
script:
- dotnet nuget push artifacts/*.nupkg \
--source "$STAGING_FEED" \
--api-key "$STAGING_API_KEY"
The release stage should run only after approval:
release:
script:
- dotnet nuget push artifacts/*.nupkg \
--source "$NUGET_FEED" \
--api-key "$NUGET_API_KEY"
The exact YAML syntax depends on the CI/CD platform, but the release design remains the same.
Common Mistakes
Publishing From a Developer Machine
Manual publishing makes it difficult to know exactly which source code, build configuration, and package was released.
A CI/CD pipeline provides a repeatable release process.
Testing the Project Instead of the Package
A project can pass all tests while its NuGet package is broken.
Always test the actual .nupkg artifact.
Reusing Package Versions
Do not keep publishing the same version while changing its contents.
Create a new version when the package changes.
Giving Build Jobs Production Credentials
Most pipeline stages do not need access to the public NuGet API key.
Keep production credentials restricted to the release stage.
Skipping Integration Testing
Unit tests are important, but package consumers may use the library differently.
A small consumer application can catch packaging and dependency problems that unit tests miss.
Best Practices
Area | Recommended approach |
|---|
Package creation | Create packages in CI |
Versioning | Use immutable package versions |
Testing | Test the actual NuGet artifact |
Staging | Publish to a private feed first |
Approval | Require approval before public release |
Credentials | Store API keys as CI secrets |
Validation | Inspect package contents and metadata |
Release | Publish the exact validated artifact |
Rollback | Release a new fixed version instead of replacing one |
One important detail is the last one: the package approved during staging should be the exact package published publicly.
Do not rebuild the project between approval and production publication.
Otherwise, the artifact that was tested may not be the artifact that consumers receive.
Advantages
A staged NuGet release process provides several practical benefits.
Lower Release Risk
Problems can be detected before public distribution.
Better Auditability
The pipeline provides a record of when the package was built, tested, approved, and released.
Safer Credentials
Production package credentials can remain isolated from normal build jobs.
Repeatable Releases
The same process can be used for every package version.
Better Consumer Confidence
Teams consuming the package can rely on a release process that includes validation instead of receiving every successful build automatically.
Disadvantages
Staged releases also introduce some overhead.
The pipeline becomes more complex than a simple build-and-push workflow.
Maintainers also need to manage staging feeds, credentials, approval rules, and package cleanup.
For a small private library used by one application, this process may be unnecessary. For a package used by multiple applications or external consumers, the additional control can be worthwhile.
Troubleshooting
Package Cannot Be Restored From the Staging Feed
Check the configured package source:
dotnet nuget list source
Make sure the staging feed is enabled and the authentication credentials are valid.
Package Push Is Rejected
Check whether the package version already exists.
If the repository treats versions as immutable, create a new version.
Package Works With Project Reference but Fails as NuGet
Create a clean consumer project and install the package from the staging feed.
Then inspect the package contents and dependency metadata.
Production Package Differs From Staging
Make sure the release stage uses the same .nupkg generated during the build.
Do not run dotnet pack again after approval.
Summary
Publishing a NuGet package should be treated as a release process rather than a simple dotnet nuget push command.
A safer workflow separates package creation from public publication:
Build
-> Test
-> Pack
-> Validate
-> Staging Feed
-> Consumer Testing
-> Approval
-> Public NuGet Feed
The most important principle is to validate the exact package that will be released. Build the artifact once, test it from a consumer's perspective, keep production credentials protected, and publish only after the required checks have passed.
This approach adds a little more structure to NuGet releases, but it can prevent a small packaging mistake from becoming a problem for every application consuming the library.
Join the conversation! Your thoughts help the community grow.