skill by
@dotnetSet up NuGet trusted publishing (OIDC) on a GitHub Actions repo — replaces long-lived API keys with short-lived tokens. USE FOR: trusted publishing, NuGet OIDC, keyless NuGet publish, migrate from NuGet API key, NuGet/login, secure NuGet publishing. DO NOT USE FOR: publishing to private feeds or Azure Artifacts (OIDC is nuget.org only). INVOKES: shell (powershell or bash), edit, create, ask_user for guided repo setup.
Permissions
Files
Set up NuGet trusted publishing (OIDC) on a GitHub Actions repo — replaces long-lived API keys with short-lived tokens. USE FOR: trusted publishing, NuGet OIDC, keyless NuGet publish, migrate from NuGet API key, NuGet/login, secure NuGet publishing. DO NOT USE FOR: publishing to private feeds or Azure Artifacts (OIDC is nuget.org only). INVOKES: shell (powershell or bash), edit, create, ask_user for guided repo 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.
Install
It’s free, and every skill you add syncs into every AI tool on your computer, instantly.
Version history
Use this skill when:
secrets.NUGET_API_KEY to OIDC-based publishingNuGet/login@v1 or id-token: write⚠️ 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.
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.
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 toolIsPackable=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.
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 ./artifactsto verify the .nupkg is created correctly."
dotnet pack -c Release -o ./artifacts — verify .nupkg is created./artifacts, run --help, uninstall.nupkg contents (it's a zip)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.ymlorpublish.yaml) — just the filename, no path prefix. Matching is case-insensitive. Don't use the workflowname: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 usesenvironment:; 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 →
releaseAdd 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.
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.
| 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.
In these kits
More from @dotnet
Works with
Claude, Codex, Cursor & more