| name | nuget-trusted-publishing |
| description | Review, maintain, or set up NuGet trusted publishing (OIDC) for GitHub Actions. USE FOR: NuGet OIDC, keyless NuGet publish, NuGet/login, trusted-publishing policy changes, release authentication, and diagnosing NuGet trusted-publishing failures. DO NOT USE FOR: private feeds that do not support nuget.org trusted publishing.
|
| license | MIT |
NuGet Trusted Publishing
Use NuGet trusted publishing to exchange GitHub OIDC identity for a short-lived NuGet API key instead of storing a long-lived publishing key.
Dapper-FluentMap baseline: trusted publishing is already implemented in .github/workflows/release.yml through NuGet/login, a protected release environment, and job-scoped id-token: write. Treat that implementation as the baseline to preserve and review, not something to recreate from a generic sample. AGENTS.md, eng/package-catalog.json, eng/publish-package-set.ps1, release recovery, and package immutability rules are authoritative.
When to Use
- Reviewing or changing the NuGet.org publishing job.
- Diagnosing
NuGet/login, OIDC, policy, environment, or authorization failures.
- Adding a new package to the governed package family.
- Changing the release workflow filename or GitHub Environment in a way that may affect the nuget.org trusted-publishing policy.
- Verifying that release changes preserve short-lived credentials and least privilege.
Safety Rules
- Never replace OIDC with a long-lived NuGet API key merely to make a release pass.
- Never publish, tag, create a GitHub Release, or invoke recovery unless the user explicitly requests it.
- Package IDs and published versions are immutable release identities; validate before publishing.
- A NuGet.org flat-container
404 proves only that a package/version is not currently present. It does not prove that the publisher is authorized to create that PackageId.
- Preserve partial-release recovery: validate existing registry artifacts and publish only missing artifacts rather than deleting or overwriting package versions.
Repository Assessment
Before changing trusted publishing, inspect:
.github/workflows/release.yml and release-recovery-missing-nuget.yml.eng/package-catalog.json for the exact five governed PackageIds.eng/publish-package-set.ps1 for publication/idempotency behavior.eng/validate-release-artifacts.ps1 and consumer-smoke validation.- The
release environment and the exact nuget.org trusted-publishing policy values when external configuration is involved.
Current governed package family:
Dapper.FluentMapDapper.FluentMap.DommelFluentMap.DependencyInjectionFluentMap.AnalyzersFluentMap.Generators
Project identity, assembly identity, namespace identity, and NuGet PackageId are independent. Do not rename projects/assemblies/namespaces as a side effect of a publishing change.
Trusted Publishing Pattern
The NuGet publishing job should retain the equivalent of:
permissions:
contents: read
id-token: write
- name: Exchange GitHub OIDC token for temporary NuGet API key
id: nuget-login
uses: NuGet/login@<approved-pinned-sha>
with:
user: "${{ vars.NUGET_USER }}"
The temporary key is then passed only to the governed publication step. Keep NuGet/login SHA-pinned according to repository policy.
Policy Coupling
The nuget.org trusted-publishing policy is coupled to GitHub identity. Changes to these values may require external policy updates:
- repository owner/name;
- publishing workflow filename;
- GitHub Environment name;
- nuget.org account/package ownership.
Do not claim external policy changes are complete unless they are verified.
Validation
For code-only release changes, validate the existing deterministic release pipeline rather than performing a real publish:
- workflow schema/actionlint where applicable;
- restore/build/test/pack;
- package metadata and artifact-manifest validation;
- consumer-smoke tests;
- package catalog consistency;
- least-privilege permissions and OIDC path.
A real publish is required only when the user explicitly asks for release execution.
Troubleshooting
| Problem | Likely cause | Check |
|---|
NuGet/login 403 | OIDC permission/policy mismatch | id-token: write, policy repo/workflow/environment |
| No matching policy | Workflow/environment identity mismatch | Exact nuget.org policy values |
| Push unauthorized | Package ownership/policy authorization | Package owner/publisher configuration |
| Temporary key expired | Login too early | Move token exchange close to publication |
| Package already exists | Re-run/partial release | Validate existing artifact and publish only missing packages |
References
