NuGet Repositories, API Keys, Feeds, Symbols, Proxying, and .NET Package Workflows: Configuration, Design Choices, and Tradeoffs

1. Configuration decisions live in different layers

A NuGet production design spans Nexus repository topology, Nexus authorization, proxy upstreams, client nuget.config, local package caches, CI secret handling, and optionally debugger symbol configuration. Changing one does not automatically change the others. This separation is the foundation for maintainable decisions.

2. One group source: excellent ergonomics, limited visibility into member choice

A single group URL reduces client drift: one source can expose internal hosted packages plus a curated public proxy. Nexus can put hosted members before proxy members and centralize upstream access. This is a strong default when package namespaces are unambiguous.

The tradeoff is that client-side Package Source Mapping sees only the group, not its hidden member repositories. If a public upstream can legitimately publish the same internal package ID, stronger repository-side namespace controls or a separate internal source are needed.

3. Multiple sources plus Package Source Mapping

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="Internal" value="https://repo.example.invalid/repository/nuget-internal/index.json" protocolVersion="3" />
    <add key="Public" value="https://repo.example.invalid/repository/nuget-public/index.json" protocolVersion="3" />
  </packageSources>
  <packageSourceMapping>
    <packageSource key="Internal">
      <package pattern="Contoso.*" />
    </packageSource>
    <packageSource key="Public">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Every direct and transitive dependency must match a mapping pattern. Restore errors during rollout are useful evidence of missing policy coverage. A mapping controls client source eligibility; it does not authenticate the client or change Nexus repository membership.

4. Credential design: convenience versus exposure

5. Prefer V3, understand V2 rather than pretending it disappeared

Modern NuGet and dotnet workflows should use V3 index.json. Nexus still supports a subset of V2 for compatibility. Older V2-dependent tools and custom OData queries may not be fully compatible with current H2/PostgreSQL-backed Nexus behavior. Do not infer “Nexus supports V2” to mean every deprecated NuGet Gallery query is supported forever.

Chocolatey is a current example of why protocol boundaries matter: Nexus 3.95 added Chocolatey support through NuGet repositories, but mixed V2/V3 group behavior has client-specific constraints. Keep Chocolatey as a separate tested workflow rather than assuming ordinary dotnet restore behavior applies.

6. Release mutability: Disable redeploy is the safer default

A package ID/version should identify one accepted byte sequence. Disable redeploy prevents accidental replacement. Allow redeploy makes the coordinate mutable and can cause clients/caches to disagree about what “1.0.0” means. Read-only is appropriate when publication should stop entirely.

If a build is wrong, publish a new version. Do not rebuild the same version and overwrite it as a normal release process.

7. Symbol retention is a debugging policy

Symbols can be large and may contain source/document references. Decide retention based on incident-debugging requirements, release-support windows, privacy, and storage cost. The package and symbol package should be generated from the same build, but they may have different access and retention expectations.

On Nexus 3.95+, .snupkg plus SymSrv support are current. Older Nexus deployments should not be taught to “repair” a symbol endpoint that did not exist in their version.

8. Three cache layers that operators confuse

Clear or relocate the smallest relevant cache during diagnosis. Do not delete server blobs because a client global-package folder is stale.

9. Worked design: internal libraries plus public OSS

A 60-developer team publishes Acme.* packages, restores hundreds of public packages, runs CI on Linux and Windows, and needs reproducible incident debugging. It cannot tolerate an Acme.* package coming from nuget.org.

10. Community versus optional enterprise capabilities

The mandatory design uses Community-compatible NuGet repositories, API-key realm, local users/roles, file blob storage, and single-node operation. Pro-only SSO, HA, user tokens, cloud storage, staging, and advanced platform integrations are optional architecture extensions. Do not make a developer's ability to restore or publish a lab package depend on those features.

11. Decision checklist

• Which package IDs are organization-owned?
• Can public upstreams ever satisfy those IDs?
• How many client-visible sources are truly necessary?
• Is V3 explicitly configured with /index.json?
• Is release redeployment disabled?
• Where are read credentials and deployment keys stored and rotated?
• What symbol retention/debugging requirement exists?
• How will source selection and exact package bytes be proven during an incident?

Knowledge check

12. Summary

Production NuGet design is a set of explicit boundaries: namespace, source, protocol, write target, credential type, cache, release policy, and symbol retention. Lesson 4 uses those boundaries to diagnose failures without destructive shortcuts.

Official references and version notes

• Sonatype: NuGet Repositories — hosted/proxy/group, V2/V3, authentication, Chocolatey, and symbol-server support.
• Sonatype: Configure NuGet With Nexus and NuGet CLI Usage.
• Sonatype: Realms — NuGet API-Key Realm.
• Sonatype: Tasks — current NuGet symbol-index repair task and maintenance cautions.
• Microsoft: NuGet.Config reference and Package Source Mapping.
• Microsoft: authenticated feeds — NuGetPackageSourceCredentials_* environment variables.
• Microsoft: dotnet nuget push and symbol packages (.snupkg).
• Microsoft: NuGet HTTPS Everywhere.
• Microsoft: .NET 10 downloads.

Version-sensitive statements were rechecked on 2026-08-26. The mandatory lab assumes a disposable self-hosted Nexus Repository Community Edition 3.95.2 instance, Java 21 on the Nexus side, and .NET 10 SDK 10.0.400 on the client side. The NuGet symbol/Chocolatey features used here were introduced in Nexus 3.95.0. Record the actual dotnet --info and Nexus version in evidence before execution.