Steeltoe.Management.GitProperties.Build 4.3.0

Steeltoe.Management.GitProperties.Build

Generates a git.properties file at build time, compatible with the Spring Boot Actuator git.properties format. When used together with Steeltoe's Info actuator endpoint, the information in this file (commit ID, branch, tags, whether the repository was "dirty" at build time, etc.) is automatically exposed at runtime.

Getting started

dotnet add package Steeltoe.Management.GitProperties.Build

No other setup is required for a project that references Steeltoe.Management.Endpoint and lives inside a Git repository. The next time you build that project, a git.properties file is generated and copied into your build (and publish) output automatically. Steeltoe's Info actuator endpoint then picks it up automatically at runtime. This package doesn't add any runtime dependency to your application.

Example output

A generated git.properties file looks like this:

git.branch=main
git.commit.id=1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
git.commit.id.abbrev=1a2b3c4
git.commit.id.describe=v1.4.0-3-g1a2b3c4
git.commit.time=2026-06-18T09:42:11+00:00
git.commit.message.short=Fix null reference in health check
git.commit.message.full=Fix null reference in health check\nAdds a null check before calling Ping().
git.commit.user.name=Jane Doe
git.commit.user.email=jane.doe@example.com
git.build.host=build-agent-03
git.build.user.name=Jane Doe
git.build.user.email=jane.doe@example.com
git.tags=
git.closest.tag.name=v1.4.0
git.closest.tag.commit.count=3
git.remote.origin.url=https://github.com/example-org/example-app.git
git.total.commit.count=482
git.dirty=false
git.build.version=1.4.0
git.build.time=2026-07-09T14:32:10-06:00

When Steeltoe's Info actuator endpoint is enabled, all of these values are automatically surfaced under the git key of that endpoint's response. You don't need to read this file yourself.

Shared cache

Computing repository-wide information (commit ID, branch, tags, and so on) is relatively expensive, especially when repeated for every project and target framework in a large solution. This package computes it at most once per build instead, and stores the result in a shared cache file, obj/git.properties.cache, at the root of your Git repository. Every project that generates git.properties reuses that shared cache.

The cache refreshes automatically whenever something changes in your Git repository, for example after pull, checkout, commit/tag, or merge/rebase. If you ever need to force a refresh yourself, delete the git.properties.cache file and rebuild.

One thing isn't cached, though: whether your repository is "dirty" can change between builds without a commit, tag, or anything else the cache watches for. Each project checks that freshly with its own git invocation, every time it builds.

Configuration

All settings are optional MSBuild properties, set in your project file (or a Directory.Build.props file):

Diagnostics

This package may log one of the following codes:

Deploying without access to your Git repository

By default, git.properties is generated using live information read directly from your local .git directory. It only ends up in your build or publish output directory. This works well when the system that builds or publishes your application also has access to that same .git directory.

Some deployment methods don't give the build step access to your .git directory at all. For example, pushing your application's source code straight to Cloud Foundry (cf push) does not include your .git directory, so no git.properties can be produced.

To work around this, run the following command locally before every push. Your .git directory must be available when you run it:

dotnet build -t:WriteGitPropertiesFallbackFile

This command writes an extra copy of git.properties directly next to your project file without running a full build.

git.properties

Refreshing many projects at once

The command above works for one project at a time. If your solution has several projects, and only some of them use this package, running the same command on a project that doesn't use it fails with an error like this:

error MSB4057: The target "WriteGitPropertiesFallbackFile" does not exist in the project.

To safely refresh every project at once, add a Directory.Build.targets file that applies to all of them (your solution's root folder works well). It defines a new target that only calls the real one on projects that use this package. This makes it safe to run on every project, even ones that don't use this package:

<Project>
  <Target Name="RefreshGitPropertiesFallbackFile">
    <CallTarget Targets="WriteGitPropertiesFallbackFile" Condition="'$(GitExecutable)' != ''" />
  </Target>
</Project>

Then, instead of the command shown above, run this new target for your whole solution:

dotnet build YourSolution.slnx -t:RefreshGitPropertiesFallbackFile

Using this package in a shared project

Installing this package as shown under Getting started, whether with the dotnet CLI or Visual Studio's Add Package dialog, writes PrivateAssets="all" into the <PackageReference> line automatically. This stops the reference from becoming transitive, so git.properties generation stays local to the project you installed it in. That's the right choice for most solutions: usually only a few host apps need git.properties, so keeping the reference non-transitive avoids running Git commands anywhere else.

Some solutions centralize Steeltoe registration in one shared project instead, for example an Aspire ServiceDefaults project used by several host apps. In that case, install this package once, in the shared project, and make the reference transitive so every host app referencing it generates its own git.properties file.

To make the reference transitive, add PrivateAssets="none" to this package's PackageReference in the shared project. Also set GenerateGitProperties to false on the shared project itself, since it isn't a deployable host app and doesn't need its own git.properties file:

<PropertyGroup>
  <GenerateGitProperties>false</GenerateGitProperties>
</PropertyGroup>

<ItemGroup>
  <PackageReference Include="Steeltoe.Management.Endpoint" Version="..." />
  <PackageReference Include="Steeltoe.Management.GitProperties.Build" Version="..." PrivateAssets="none" />
</ItemGroup>

Host apps referencing ServiceDefaults need no changes. Each host app keeps the default GenerateGitProperties setting (auto), detects the transitive reference to Steeltoe.Management.Endpoint coming from ServiceDefaults, and generates its own git.properties file.

Good to know

• Cross-platform. Works the same way on Windows, Linux, and macOS.
• Skips cleanly for anticipated Git issues. If a Git repository can't be found or read for one of the reasons listed in Diagnostics, generation is skipped with a message you can suppress (see GitPropertiesEnableWarnings), instead of failing your build. This makes it safe to add this package to projects that aren't always built inside a Git checkout, such as a Docker image build stage.
• Git worktrees and submodules are supported. A build running from a worktree writes git.properties for that worktree's own checked-out branch and commit, with its own independent shared cache. A submodule is treated as the fully independent repository it is, with its own commit history separate from the repository it's nested in.
• Shallow clones are supported. git.total.commit.count and git.closest.tag.commit.count are left empty, because a shallow clone doesn't have the full commit history needed to count them. This is reported via GITPROPS006 (see Diagnostics), so it's never silently incomplete.
• Detached HEAD is supported. When building for a pull request, such as in GitHub Actions, Azure DevOps, or Jenkins, well-known environment variables are used to determine the branch name.
• Git v2.15.0 or later must be installed. The git command must be runnable during your build, either on the PATH or at a location you configure with GitExecutable.
• An IDE build might not notice a new commit, branch, or tag. Visual Studio and similar IDEs can skip invoking a real build for a project when none of the files they track (source code, project file, references) have changed, even if you've committed, switched branches, or created a tag since the last build. If git.properties looks out of date, force a full rebuild, or build from the command line with dotnet build.
• File deletions inside .git aren't tracked. The shared cache only refreshes when a file is added or changed, not when one is deleted. For example, deleting a tag (git tag -d) or turning a shallow clone into a full one (git fetch --unshallow) doesn't invalidate the cache by itself. It catches up automatically the next time something else in git changes.
• Changing your global Git username or email isn't tracked. The shared cache doesn't notice when you update your name or email in Git's global settings. It catches up automatically the next time something else changes.