dotnet/sourcelink: Source Link setup for .NET libraries

Why dotnet/sourcelink changes dependency debugging

Source Link addresses a specific gap in distributed debugging. A NuGet consumer may have symbols for a dependency without having the library's complete source tree beside the binary. Source control metadata embedded in PDBs, binaries, or packages lets a compatible debugger connect the compiled code to the original commit and retrieve the relevant source file.

The primary audience is the author of a .NET library, not an application developer searching for missing local files. The repository states that Microsoft libraries, including .NET Core and Roslyn, have enabled Source Link. Visual Studio 15.3 and later can read Source Link information from symbols, while Visual Studio 15.7 and later can also retrieve files from private GitHub and Azure DevOps repositories that require authentication.

This matters most for package-based delivery. The debugger can use the commit-specific URL recorded by the build rather than assuming that the library matches whatever source currently resides at the repository's default branch. The documented flow also requires distributing PDBs. Metadata without usable symbols does not provide the complete debugging path described by the project.

The README identifies three separate responsibilities: put source control information in PDBs, include source control information in the NuGet package manifest, and distribute the PDBs. Treating Source Link as a single automatic feature leaves gaps. A build may contain usable debug metadata while its NuGet manifest omits repository details, or the package may be published without retaining the portable PDB files needed by consumers.

The metadata path from Git commit to debugger

Source Link is language agnostic and source control agnostic at the specification level. For the .NET tooling described here, provider implementations inspect the repository associated with a build and record source control information for the produced artifacts. A debugger later reads that information from symbols and uses it to locate the source associated with the compiled code.

The repository links to a separate Source Link specification that permits metadata in symbols, binaries, and packages. In the standard .NET library workflow, the PDB is the principal debugging artifact, while the NuGet manifest can publish the repository URL through its repository element. Visual Studio can then download the appropriate source, including from raw GitHub content, when the recorded revision identifies the exact file.

The revision-specific part is central. A repository's current branch can move after a package is released. Source Link records the source control relationship needed to find the matching source revision, rather than making the package depend on a source tree being installed on the consumer's machine.

Untracked source files need separate treatment because repository metadata alone may not identify content that was never committed. The documented `EmbedUntrackedSources` property embeds those files in the PDB. That setting is optional and is enabled by default in .NET SDK 8+, according to the README. It applies specifically to files not tracked by the source control manager, so it does not replace Source Link for normal committed files.

SDK 8 removes most provider-specific project references

A .NET SDK 8+ project does not need a Source Link package or additional build properties when it uses GitHub, GitHub Enterprise, Azure Repos, GitLab 12.0 or later, or Bitbucket 4.7 or later. Those provider combinations are included in the SDK and enabled by default.

That default narrows the practical installation path. There is no need to add `Microsoft.SourceLink.GitHub`, for example, merely to obtain the standard GitHub behavior in an eligible .NET SDK 8+ build. A project on an older SDK, an unsupported provider, or an older server release must instead add the provider-specific `PackageReference`.

The README warns that referencing any Source Link package in a .NET SDK 8+ project overrides the Source Link version included in the SDK. That makes package selection an explicit compatibility choice. An SDK-integrated project has the shortest configuration, while an explicit reference gives providers outside the default set a route into the build.

Source Link is a build-time dependency. The documentation recommends setting `PrivateAssets` to `all` on its package reference so consuming projects do not attempt to install it. For a library, that distinction fits the architecture: Source Link participates when the library is built, while downstream users consume the resulting package and debug artifacts rather than rebuilding the library from source.

A first .NET package build with GitHub metadata

For a GitHub repository running an older.NET SDK, begin with the provider package documented by the repository. `PrivateAssets="All"` keeps this development dependency from flowing to consuming projects.

<ItemGroup>
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All"/>
</ItemGroup>

A NuGet-producing project can also publish the repository URL in its manifest. The README presents this as optional and identifies the destination as the NuSpec repository element.

<PropertyGroup>
  <PublishRepositoryUrl>true</PublishRepositoryUrl>
</PropertyGroup>

A library author would use the normal restore and build process for the project, then publish the PDBs as a separate distribution requirement. The expected build result is source control information associated with the PDB and, when enabled, a repository entry in the `.nupkg` manifest.

For committed GitHub sources on.NET SDK 8+, omit the explicit package reference and retain the manifest setting if the repository URL should appear in the package. The README's version table also shows release packages associated with.NET 10 and an early.NET 11 preview, but it does not state that a new project must select one of those versions for Source Link itself.

Private hosts and older server formats need explicit configuration

Provider packages do not make every server layout equivalent. An on-premises Azure DevOps Server installation may need both the matching package and its hostname. If the server uses a non-empty IIS virtual directory, the same item also needs a `VirtualDirectory` value.

<ItemGroup>
  <SourceLinkAzureDevOpsServerGitHost Include="server-name" VirtualDirectory="tfs"/>
</ItemGroup>

The `Include` value accepts a domain and can include a port such as `server-name:8080`. This matters because the generated source retrieval URLs must match how the server exposes its Git repositories. A package reference alone cannot describe that deployment-specific host configuration.

GitLab has a similar version boundary. `Microsoft.SourceLink.GitLab` 8.0.0 and later assume GitLab 12.0 or later because the file-access URL format changed at that release. An older server requires the host and its version to be stated explicitly.

<ItemGroup>
  <SourceLinkGitLabHost Include="gitlab.yourdomain.com" Version="11.0"/>
</ItemGroup>

These cases show the main configuration cost beyond .NET SDK 8+. The work is not simply enabling a flag. Library authors must know the hosting product, server generation, hostname, optional port, virtual path, and whether consumers' debuggers can authenticate against that host.

Authentication, symbols, and access remain separate constraints

Source Link metadata is only one part of source debugging. The README identifies PDB distribution as a separate step, and private repository retrieval has its own debugger requirements. Visual Studio 15.7 or later is documented as able to download source files from private GitHub and Azure DevOps repositories that require authentication. Earlier Visual Studio versions are not documented here as having that private-repository capability.

This creates a concrete failure case. A package can carry valid Source Link metadata and still fail to show source for a consumer if the PDB was not distributed, the consumer has no compatible symbols, authentication is unavailable, or the repository endpoint no longer grants access.

The direct source embedding alternative addresses only part of this problem. `EmbedUntrackedSources` places untracked files into the PDB, which is useful when committed repository mapping cannot identify them. It is not presented as a complete replacement for retrieving committed source from a private or public repository. A different distribution strategy may be appropriate when the debugging environment cannot reach the configured source host, but the README does not specify such an alternative workflow in enough detail to prescribe one.

For adoption decisions, the useful comparison is therefore between remote, revision-specific retrieval and shipping all relevant source through another channel. Source Link favors smaller normal source retrieval tied to repository metadata, while explicit embedding changes where source content travels. Neither option removes the need to supply symbols or verify client access.

Maintenance signals and the cost of changing providers

The repository is not archived, and its last push was on 2026-10-14. Recent releases include `v10.0.103` for.NET 10.0.103 and `v11.0.0-preview.1.26104.118` for.NET 11 Preview 1, both dated 2026-02-17. These facts show current release activity, but the README does not document a compatibility matrix or a long-term support policy that would map every Source Link package version to every SDK and source host.

Migration cost is more concrete for source hosting changes. Moving from a supported Git provider may remove the need for a project reference under.NET SDK 8+, while moving to an unsupported host requires the matching provider package. Server installations can add host items, ports, and virtual directories. Existing GitLab deployments older than 12.0 also carry server-version metadata into project configuration.

The project is licensed under MIT. Source Link packages are build dependencies, and the recommended `PrivateAssets="All"` setting prevents them from becoming dependencies of consuming projects.

Editorial conclusion

Source Link suits authors who publish .NET libraries and want consumers to step through readable source rather than only symbols. It is less appropriate when the project targets an unsupported source host, uses a debugger without the documented Source Link support, or cannot distribute usable PDB files. Verify first that the repository provider is detected, the produced package contains repository information, and the intended debug clients can retrieve both the symbols and their referenced source files.

Frequently asked questions

Official sources

1. dotnet/sourcelink on GitHub
2. Issues
3. License: MIT
4. README
5. Releases