Nuget Trusted Publishing

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:

   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:

   - 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:

   --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