nuget-trusted-publishing

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:

1. .github/workflows/release.yml and release-recovery-missing-nuget.yml.
2. eng/package-catalog.json for the exact five governed PackageIds.
3. eng/publish-package-set.ps1 for publication/idempotency behavior.
4. eng/validate-release-artifacts.ps1 and consumer-smoke validation.
5. The release environment and the exact nuget.org trusted-publishing policy values when external configuration is involved.

Current governed package family:

• Dapper.FluentMap
• Dapper.FluentMap.Dommel
• FluentMap.DependencyInjection
• FluentMap.Analyzers
• FluentMap.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

• references/package-types.md
• references/publish-workflow.md
• NuGet Trusted Publishing