NuGet Trusted Publishing Setup

Set up NuGet trusted publishing on a GitHub Actions repo. Replaces long-lived API keys with OIDC-based short-lived tokens — no secrets to rotate or leak.

Prerequisites

GitHub Actions — this skill covers GitHub Actions setup only
nuget.org account — the user needs access to create trusted publishing policies

When to Use This Skill

Use this skill when:

Setting up trusted publishing for a NuGet package
Migrating from
```
secrets.NUGET_API_KEY
```
to OIDC-based publishing
Asked about keyless or secure NuGet publishing
Creating a new NuGet publish workflow from scratch
Asked to "remove NuGet API key" or "use NuGet/login"
Setting up publishing for a dotnet tool, MCP server, or template package
Asked about
```
NuGet/login@v1
```
or
```
id-token: write
```

Safety Rules

⚠️ Bail-out rule: If any phase fails after one fix attempt on an infrastructure/auth issue, stop and ask the user. Don't loop on environment problems.

⚠️ Never delete or overwrite without confirmation: Removing API key secrets, deleting tags/releases, removing workflow steps, or changing package IDs. NuGet package IDs are permanent — mistakes can't be undone.

Process

Fast-path for greenfield repos: When the user has a simple setup (one packable project, no existing publish workflow), don't gate on multi-turn assessment. Combine phases: create the workflow immediately, include nuget.org policy guidance, local pack recommendation, and filename-matching warning all in one response. The full phased process below is for complex or migration scenarios.

Phase 1: Assess

Inspect the repo and report findings before making any changes.

Find and classify packable projects — check
```
.csproj
```
files and
Directory.Build.props
(package metadata is often set repo-wide). Classify in this order (earlier matches win):
- ```
<PackageType>Template</PackageType>
```
  → Template
- ```
<PackageType>McpServer</PackageType>
```
  → MCP server (also a dotnet tool)
- ```
<PackAsTool>true</PackAsTool>
```
  → Dotnet tool
- Class library (
```
IsPackable=true
```
  or no
```
OutputType
```
  ) → Library
- ```
<OutputType>Exe</OutputType>
```
  with
```
<IsPackable>true</IsPackable>
```
  → Application package (not a tool, but still publishable)
- ```
<OutputType>Exe</OutputType>
```
  without
```
PackAsTool
```
  or
```
IsPackable
```
  → Not packable by default (ask user if they intend to publish it)

Validate structure for each project's type:

Type	Required
All	`PackageId` , `Version` (in .csproj or Directory.Build.props)
Dotnet tool	`PackAsTool` (required); `ToolCommandName` (optional but recommended — defaults to assembly name)
MCP server	`PackageType=McpServer` , `.mcp/server.json` included in package
Template	`PackageType=Template` , `.template.config/template.json` under content dir

Find existing publish workflows in

.github/workflows/

— look for

dotnet nuget push

nuget push

, or

dotnet pack

Check version consistency — for MCP servers, verify
```
.csproj
```
```
<Version>
```
matches both
```
server.json
```
version fields (root
```
version
```
and
```
packages[].version
```
). Flag any mismatch.
Report findings to the user: classification, missing properties, version mismatches, existing workflows. For multi-project repos, note whether one workflow or separate workflows per package are needed. Offer to fix gaps — use
```
ask_user
```
before modifying project files.

❌ See references/package-types.md for per-type details and required properties.

Phase 2: Local Verification

Pack and verify locally before touching nuget.org — publishing errors waste a permanent version number.

⚠️ Always mention this step, even if you defer running it. Tell the user: "Before your first publish, run
dotnet pack -c Release -o ./artifacts
to verify the .nupkg is created correctly."

dotnet pack -c Release -o ./artifacts

— verify

.nupkg

is created

For tools/MCP servers: install from
```
./artifacts
```
, run
```
--help
```
, uninstall
For libraries: inspect the
```
.nupkg
```
contents (it's a zip)

Phase 3: nuget.org Policy

This phase requires the user to act on nuget.org — guide them with exact values.

Determine the repo owner, repo name, and the workflow filename that will publish.
❌ The policy requires the exact workflow filename (e.g.,
publish.yml
or
publish.yaml
) — just the filename, no path prefix. Matching is case-insensitive. Don't use the workflow
name:
field.
Guide the user to create the trusted publishing policy:
Go to nuget.org/account/trustedpublishing → Add policy
- Repository Owner:
  {owner}
- Repository:
  {repo}
- Workflow File:
  {filename}.yml
- Environment:
  release
  (only if the workflow uses
  environment:
  ; leave blank otherwise)
Policy ownership: the user chooses individual account or organization. Org-owned policies apply to all packages owned by that org.

For private repos: policy is "temporarily active" for 7 days — becomes permanent after the first successful publish.
Guide the user to create a GitHub Environment (recommended but optional — provides secret scoping + approval gates):
Repo Settings → Environments → New environment →
release
Add environment secret: Name =
NUGET_USER
, Value = nuget.org username (NOT email)
Optional: add Required reviewers for an approval gate.

⚠️ Wait for the user to confirm they've created the policy before asking them to remove old API keys/secrets or before attempting to run/publish with the workflow. Drafting or showing the workflow file itself is OK before confirmation.

Phase 4: Workflow Setup

Create or modify the publish workflow. The workflow must always be created or shown in your response — you may draft/show it even if the nuget.org policy is not yet confirmed, but do not guide the user to actually run/publish or remove old secrets until after confirmation.

Greenfield: Create

publish.yml

from the template in references/publish-workflow.md. Adapt .NET version, project path, and environment name. Ensure your output explicitly mentions

id-token: write

and

NuGet/login@v1

Migration (existing workflow with API key): Modify in place —

Add OIDC permission and environment to the publishing job:

yaml

jobs:
  publish:
    environment: release
    permissions:
      id-token: write     # Required — without this, NuGet/login fails with 403
      contents: read      # Explicit — setting permissions overrides defaults

Add the NuGet login step before push:

yaml

- name: NuGet login (OIDC)
  id: login
  uses: NuGet/login@v1
  with:
    user: ${{ secrets.NUGET_USER }}  # nuget.org profile name, NOT email

Replace the API key in the push step:

yaml

--api-key ${{ steps.login.outputs.NUGET_API_KEY }} --skip-duplicate

Verify: Ask the user to trigger a publish and confirm the package appears on nuget.org.

❌ Don't delete the old API key secret until trusted publishing is verified. Removing it is a one-way door — wait for confirmation.

Troubleshooting

Problem	Cause	Fix
`NuGet/login` 403	Missing `id-token: write`	Add to job permissions
"no matching policy"	Workflow filename mismatch	Verify exact filename on nuget.org
Push unauthorized	Package not owned by policy account	Check policy owner on nuget.org
Token expired	Login step >1hr before push	Move `NuGet/login` closer to push
"temporarily active" policy	Private repo, first publish pending	Publish within 7 days
`already_exists` on push	Re-running same version	Add `--skip-duplicate`
GitHub Release 422	Duplicate release for tag	Delete conflicting release (confirm first)
Re-run uses wrong YAML	`gh run rerun` replays original commit's YAML	Delete obstacle, re-run — never re-tag

⚠️ If any blocker persists after one fix attempt, stop and ask the user.

References

Package type details: references/package-types.md — detection logic, required properties, minimal .csproj examples
Publish workflow template: references/publish-workflow.md — complete tag-triggered workflow ready to adapt
Microsoft docs: NuGet Trusted Publishing

nuget-trusted-publishing

NPX Install

Tags

SKILL.md Content

NuGet Trusted Publishing Setup

Prerequisites

When to Use This Skill

Safety Rules

Process

Phase 1: Assess

Phase 2: Local Verification

Phase 3: nuget.org Policy

Phase 4: Workflow Setup

Troubleshooting

References