From 76d745782f8e581221098936bb6c0682731a567b Mon Sep 17 00:00:00 2001 From: James Crosswell Date: Mon, 4 May 2026 15:38:32 +1200 Subject: [PATCH] docs(dotnet): Add Docker build guidance to MSBuild setup page Document the two Docker-specific gotchas when using Sentry CLI via MSBuild: passing SENTRY_AUTH_TOKEN as a build arg and promoting it to an ENV var, and using -p:UseSentryCLI=false in the publish stage of a multi-stage Dockerfile to avoid errors when project source is not present. Includes a complete multi-stage Dockerfile example for ASP.NET Core. Refs getsentry/sentry-dotnet#2420 Co-Authored-By: Claude --- .../dotnet/common/configuration/msbuild.mdx | 75 +++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/docs/platforms/dotnet/common/configuration/msbuild.mdx b/docs/platforms/dotnet/common/configuration/msbuild.mdx index ad46127c30502..db3dbb9bcea7f 100644 --- a/docs/platforms/dotnet/common/configuration/msbuild.mdx +++ b/docs/platforms/dotnet/common/configuration/msbuild.mdx @@ -46,6 +46,9 @@ However, we generally recommend the following: You do not need to separately install Sentry CLI on your build server, as it is already provided by the Sentry NuGet package. +- If building inside a **Docker container**, use a [BuildKit secret](https://docs.docker.com/build/building/secrets/) to pass the auth token securely. + See [Building with Docker](#building-with-docker) below for a complete example. + ## Configuration In addition to authentication, you must configure your Sentry organization and project slugs. @@ -259,3 +262,75 @@ them, be very careful that their values are not committed to source control or a A more secure approach is to set authentication via environment variable or `~/.sentryclirc` file, + +## Building with Docker + +When building inside a Docker container, there are two things to handle: passing the auth token securely, and avoiding errors in multi-stage builds. + +### Passing the Auth Token + +Use Docker BuildKit's `--secret` flag to pass the auth token at build time. Unlike `ARG`/`ENV`, BuildKit secrets are never written to any image layer and do not appear in `docker history`. + +Pass the secret when building the image: + +```bash +docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN . +``` + +In your Dockerfile, mount the secret only for the `RUN` instruction that performs the build: + +```dockerfile +RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \ + dotnet build "MyWebApp.csproj" --no-restore -c Release -o /app/build +``` + +The `env=` option exposes the secret as the `SENTRY_AUTH_TOKEN` environment variable for the duration of that `RUN` instruction only — exactly what the Sentry CLI needs — without persisting it to a layer. + + + +BuildKit is enabled by default in Docker 23.0 and later. For older versions, set `DOCKER_BUILDKIT=1` in your environment before running `docker build`. + + + +### Multi-Stage Dockerfiles + +If your Dockerfile has separate stages for `dotnet build` and `dotnet publish` (a common pattern for ASP.NET Core apps), Sentry CLI only needs to run during the **build** stage. The publish stage copies compiled output and doesn't have access to the full project source, so running Sentry CLI there will fail. + +Disable Sentry CLI in the publish stage by passing `-p:UseSentryCLI=false` to `dotnet publish`: + +```dockerfile +RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish -p:UseAppHost=false -p:UseSentryCLI=false +``` + +### Complete Example + +The following is a complete multi-stage Dockerfile for an ASP.NET Core app. It assumes ``, ``, ``, and `` are configured in your `.csproj` or `Directory.Build.props`. + +```bash +# Build: docker build --secret id=sentry_auth_token,env=SENTRY_AUTH_TOKEN . +``` + +```dockerfile +FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base +WORKDIR /app +EXPOSE 8080 + +FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build +WORKDIR /src +COPY ["MyWebApp.csproj", "./"] +RUN dotnet restore "MyWebApp.csproj" +COPY . . + +# The secret is available only for this RUN instruction and is never written to a layer. +RUN --mount=type=secret,id=sentry_auth_token,env=SENTRY_AUTH_TOKEN \ + dotnet build "MyWebApp.csproj" --no-restore -c Release -o /app/build + +# Sentry CLI already ran during the build stage, so disable it here. +FROM build AS publish +RUN dotnet publish "MyWebApp.csproj" -c Release -o /app/publish -p:UseAppHost=false -p:UseSentryCLI=false + +FROM base AS final +WORKDIR /app +COPY --from=publish /app/publish . +ENTRYPOINT ["dotnet", "MyWebApp.dll"] +```