Implement time-boxed CLI telemetry with opt-out controls by arturcic · Pull Request #4927 · GitTools/GitVersion

arturcic · 2026-04-29T15:41:28Z

Description

Introduces an optional telemetry pipeline to collect CLI usage data, featuring automated redaction of paths and sensitive values. Collection is restricted to a 3-month window following the release date and supports multiple opt-out mechanisms including environment variables and a CLI flag.

Related Issue

Resolves #XYZ

Motivation and Context

This change helps maintainers make data-driven OSS design decisions by understanding common CLI patterns and environment contexts while preserving user privacy through strict redaction and transparency notices.

How Has This Been Tested?

Tested via new unit test suites covering argument parsing, redaction logic, environment-based opt-out, and release window validation.

Screenshots (if appropriate):

Checklist:

My code follows the code style of this project.
My change requires a change to the documentation.
I have updated the documentation accordingly.
I have added tests to cover my changes.
All new and existing tests passed.

arturcic · 2026-04-29T15:45:45Z

Here is a bit more context:

Implement time-boxed, privacy-focused telemetry for the GitVersion CLI.

Introduce a telemetry pipeline that collects narrow CLI usage data for a 3-month window following a release. This system includes automated redaction of sensitive paths and credentials while providing multiple opt-out mechanisms via environment variables and CLI flags.

Changes
Add CommandLineTelemetry model and TelemetryReporter to handle data collection and user disclosure.
Integrate telemetry tracking into both ArgumentParser and LegacyArgumentParser with automated PII redaction.
Update MSBuild targets to identify internal tool invocations via the GITVERSION_INTERNAL_CALLER environment variable.
Embed release date metadata into assemblies during build to enforce the three-month collection window.
Impact
Users receive a one-time disclosure notice in the console upon the first telemetry-eligible execution.
Enables maintainers to analyze CLI argument usage and CI provider distribution without collecting repository content.
Provides three opt-out methods: DO_NOT_TRACK, GITVERSION_TELEMETRY_OPTOUT, or the --telemetry-opt-out flag.
Introduces new dependencies on local application data storage for tracking the disclosure notice state.

What is left is to decide on the backend where all the usage is saved, preferable with some dashboard we can use to see the different usage types.

This is a follow up on the refactoring done for v7 where the new POSIX compliant cli was introduced. @asbjornu @gep13 @HHobeck, do you mind to have a look and suggest a backend solution for this? Thank you.

asbjornu

Great stuff! Where and how are you (or we) going to monitor the data collected?

asbjornu · 2026-05-05T10:08:03Z

@@ -0,0 +1,163 @@
+using System.Globalization;
+
+namespace GitVersion;


Should the Telemetry stuff be inside a GitVersion.Telemetry namespace, perhaps?

asbjornu · 2026-05-05T10:10:15Z

+    public const string MetadataKey = "GitVersionReleaseDate";
+    public const string Format = "yyyy-MM-dd";
+
+    public static bool TryGetReleaseDate(Assembly assembly, out DateOnly releaseDate)


Why isn't the out parameter of type TelemetryReleaseDate? That would simplify the IsWithinWindow method so it can work on the TelemetryReleaseDate instance instead of being static and taking the release date it as a DateOnly argument.

Suggested change

public static bool TryGetReleaseDate(Assembly assembly, out DateOnly releaseDate)

public static bool TryGetReleaseDate(Assembly assembly, out TelemetryReleaseDate releaseDate)

asbjornu · 2026-05-05T10:11:16Z

+        return DateOnly.TryParseExact(value, Format, CultureInfo.InvariantCulture, DateTimeStyles.None, out releaseDate);
+    }
+
+    public static bool IsWithinWindow(DateOnly releaseDate, DateOnly utcToday) =>


As per the previous suggestion, this would be easier to work with rather than having to go through DateOnly for every interaction.

Suggested change

public static bool IsWithinWindow(DateOnly releaseDate, DateOnly utcToday) =>

public bool IsWithinWindow(DateOnly utcToday) =>

asbjornu · 2026-05-05T10:11:58Z

+    public const string Verbosity = "verbosity";
+}
+
+internal static class TelemetryReleaseDate


Why not make TelemetryReleaseDate a proper value object rather than just a collection of static methods?

Suggested change

internal static class TelemetryReleaseDate

internal class TelemetryReleaseDate

asbjornu · 2026-05-05T10:18:36Z

+
+    public void AddFlag(string name) => AddValues(name, ["true"]);
+
+    public void AddValue(string name, string? value, TelemetryValueKind kind = TelemetryValueKind.Plain)


If it isn't much work, I'm thinking it would be better to have a one-time immutable mapping of all arguments we want to collect and their kind here inside TelemetryModels.cs such that it's impossible to pass the wrong kind of TelemetryValueKind, and also making the invocation of the AddValue() and AddValues() methods simpler.

Suggested change

public void AddValue(string name, string? value, TelemetryValueKind kind = TelemetryValueKind.Plain)

public void AddValue(string name, string? value)

asbjornu · 2026-05-05T10:18:56Z

+        AddValues(name, [value], kind);
+    }
+
+    public void AddValues(string name, IEnumerable<string>? values, TelemetryValueKind kind = TelemetryValueKind.Plain)


Suggested change

public void AddValues(string name, IEnumerable<string>? values, TelemetryValueKind kind = TelemetryValueKind.Plain)

public void AddValues(string name, IEnumerable<string>? values)

asbjornu · 2026-05-05T10:32:29Z

    }

-    private void MapParsedValues(Arguments arguments, ParseResult parseResult, CommandOptions options)
+    private void MapParsedValues(


It would be nice to reduce the complexity of MapParsedValues from 84 as suggested by SonarCloud. Perhaps not in this PR, but it might be relevant for what this PR wants to do to map arguments to TelemetryValueKind. So perhaps something that could be done first to make the implementation of Telemetry simpler? Make the change easy, then make the easy change. :)

arturcic · 2026-05-05T11:02:58Z

Great stuff! Where and how are you (or we) going to monitor the data collected?

That's exactly why I tagged everybody, we need to find a solution for that, and might require some infra to setup for the telemetry. If there is any past experience/ best practices from you, that would be great.

HHobeck · 2026-05-05T16:12:21Z

FYI: I have seen that reqnroll provides some reports with statistics as well. Maybe we can use the experience of the project member. Or reuse part of the source code.

https://reqnroll.net/news/2026/03/monthly-stats-2026-02/

asbjornu · 2026-05-06T12:18:41Z

That's exactly why I tagged everybody, we need to find a solution for that, and might require some infra to setup for the telemetry. If there is any past experience/ best practices from you, that would be great.

Being the maintainer of Sentry's C# SDK for a while, I have good experience with them. We can apply for an open source (free) license if we want. Sentry is at its core geared more towards error monitoring, but it can be used for analytics as well. And I think it would be useful to also implement its error reporting mechanisms into GitVersion if we choose to go in this direction.

FYI: I have seen that reqnroll provides some reports with statistics as well. Maybe we can use the experience of the project member. Or reuse part of the source code.

https://reqnroll.net/news/2026/03/monthly-stats-2026-02/

Very interesting @HHobeck! I really like the transparency. This is something we could (mostly) automate with a GitHub action to extract data from the backend we choose and create a post that can be published monthly on gitversion.net. Do you know which analytics backend Reqnroll uses?

arturcic · 2026-05-06T14:35:43Z

That's exactly why I tagged everybody, we need to find a solution for that, and might require some infra to setup for the telemetry. If there is any past experience/ best practices from you, that would be great.

Being the maintainer of Sentry's C# SDK for a while, I have good experience with them. We can apply for an open source (free) license if we want. Sentry is at its core geared more towards error monitoring, but it can be used for analytics as well. And I think it would be useful to also implement its error reporting mechanisms into GitVersion if we choose to go in this direction.

FYI: I have seen that reqnroll provides some reports with statistics as well. Maybe we can use the experience of the project member. Or reuse part of the source code.
https://reqnroll.net/news/2026/03/monthly-stats-2026-02/

Very interesting @HHobeck! I really like the transparency. This is something we could (mostly) automate with a GitHub action to extract data from the backend we choose and create a post that can be published monthly on gitversion.net. Do you know which analytics backend Reqnroll uses?

I've being researching and found https://github.com/aptabase/aptabase and https://github.com/aptabase/self-hosting, but then we need to host it ourselves

HHobeck · 2026-05-07T11:48:37Z

Please review my proposal I want to ask the maintainer of reqnroll:

Hi!

I really like the transparency reports/statistics you publish for Reqnroll. We’re discussing something similar for GitVersion and I was wondering: how did you implement the reporting pipeline?

Mainly curious about:

which analytics backend(s) you use,

how the data is collected,

where are you hosting your infra (self-hosting, third party)

whether the reports are generated automatically and

if any part of the implementation is reusable or open source?

We’re especially interested in automated monthly report generation (possibly via GitHub Actions) containng the following information:

.NET Framework Usage

CI/CD Server Usage

Visual Studio version usage

We’d love to learn from your experience before reinventing the wheel 🙂

Implement time-boxed CLI telemetry with opt-out controls #4927 (comment)

Cheers!

gep13 · 2026-05-07T12:01:30Z

Working with telemetry is not something that I have any experience with, so I am not sure how much, if any, I can offer here.

I only thing I would ask for clarification on is, is the default to opt-in to telemetry, or to opt-out? I have seen some backlash recently about decisions made to make the default opt-in for things.

gep13 · 2026-05-07T12:02:29Z

@HHobeck said...
Please review my proposol I want to ask the maintainer of reqnroll:

This looks good to me!

gep13 · 2026-05-07T12:07:22Z

The was the recent change (not linking directly)

https://github.com/cli/cli/pull/13254

arturcic · 2026-05-07T12:08:57Z

Working with telemetry is not something that I have any experience with, so I am not sure how much, if any, I can offer here.

I only thing I would ask for clarification on is, is the default to opt-in to telemetry, or to opt-out? I have seen some backlash recently about decisions made to make the default opt-in for things.

at least for OSS projects, it's said the user has to opt-out of the telemetry, and by default we will collect the telemetry (at least I've see a couple of cli tools, including dotnet doing that) And the reason for that is we as OSS we want to collect the telemetry to understand the usage and that will drive the decisions we make regarding the CLI in this case. And the idea is we want to keep it time-boxed to collect enough usage for a specific version. We could also enable the time-boxed telemetry for example only for major (and minor) version, but not for patch. We don't want to keep it enabled for too long as we need only a snapshot of the usage.

As for the opt-in or opt-out, I prefer the user to have to opt-out as I guess the users most probably will not now there is a telemetry they want to opt-in or even if they know, they might not want to.

arturcic · 2026-05-07T12:09:53Z

https://github.com/cli/cli/pull/13254

thanks for sharing

arturcic · 2026-05-07T12:11:36Z

@HHobeck said...
Please review my proposol I want to ask the maintainer of reqnroll:

This looks good to me!

same

arturcic · 2026-05-07T12:48:37Z

we could also get inspired by how homebrew does it.

What is really important is to be really transparent on what we want to collect and as seen in the brew case, have the analytics be publicaly available

sonarqubecloud · 2026-05-19T11:21:08Z

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

HHobeck · 2026-05-19T18:41:32Z

I got an answer from Gaspar:

https://github.com/orgs/reqnroll/discussions/1081

Research and phased plan for replacing LibGit2Sharp with a vendored managed reader plus git CLI writes (GitTools#5031). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…primitives New project (with NOTICE attribution for code ported from Nerdbank.GitVersioning ManagedGit) and the raw building blocks: hash-agnostic GitObjectId, zlib and random-access streams, text decoding with Latin-1 fallback, and file helpers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Packfile access with idx v2 lookup, ofs/ref delta stream application, a bounded pack memory cache with refcounted views, and multi-pack-index support. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author/committer signatures with commit-encoding handling, streaming tree reads for diff traversal, and annotated-tag target resolution. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Single lookup facade across loose objects, packs, and the multi-pack index, with SHA-256 repository detection failing fast with a clear message. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Loose and packed refs (peeled entries, symrefs, HEAD, lock-file skipping), walk-up discovery with .git-file indirection, worktree and commondir resolution, shallow detection, git config parsing, and reftable/objectformat rejection with clear messages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Time/topological sorts with exact tie-break mechanics, first-parent walks, mark-uninteresting limiting, paint-down-to-common merge-base selection, and shallow boundaries grafted parentless from .git/shallow; unexplained missing parents fail the walk. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Changed-paths tree diff aligned by raw byte order, .git/index v2-v4 reader (v4 prefix compression), gitignore matching, and the working-tree status walk matching the libgit2 adapter's uncommitted-changes expression. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Plumbing-only parsing, ArgumentList invocation with LC_ALL=C and terminal prompts disabled, per-invocation auth headers, stderr classification mapped to existing exceptions (LockedFileException retry preserved), and shared pull-request tip matching with peeled-entry folding. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Managed* adapters implement IGitRepository/IMutatingGitRepository and the collection interfaces directly over the managed reader and CLI mutator, with an immutable session snapshot invalidated after mutations. Backend selection is centralized in GitBackendSelector: GITVERSION_GIT_BACKEND picks libgit2 (default when unset) or managed at every composition root, failing fast on unrecognized values. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Deep-equality parity assertions across both backends on adversarial fixtures, plus a real-world corpus script diffing gitversion JSON output across repositories and backends. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Adds the git_backend dimension so every leg runs with libgit2 and managed, publishing per-backend test summaries and coverage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

GITVERSION_GIT_BACKEND usage, the v7.0 libgit2 default and v7.1 managed flip, and the git-on-PATH requirement scoped to normalization scenarios. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Add shared IntelliJ/Rider run configurations to facilitate debugging the CLI using both libgit2sharp and managed git backends.

Implement a telemetry pipeline to collect redacted CLI usage data for OSS design decisions. Users can opt out via environment variables `DO_NOT_TRACK`, `GITVERSION_TELEMETRY_OPTOUT`, or the `--telemetry-opt-out` flag.

Embed release dates in assembly metadata during build and disable telemetry if the window has expired or metadata is missing.

Detect the current CI environment and identify whether the CLI was invoked directly or via GitVersion.MsBuild to better understand usage patterns.

…older Organize the GitVersion.App project structure by grouping telemetry components into their own directory.

…amespaces Remove fully qualified names for build agent interfaces and assembly reflection types to improve code readability.

sonarqubecloud · 2026-07-17T15:51:52Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.7% Duplication on New Code

See analysis details on SonarQube Cloud

arturcic requested review from HHobeck, asbjornu and gep13 April 29, 2026 15:41

arturcic force-pushed the next/v7 branch from 8e722c6 to f84899d Compare May 5, 2026 09:02

arturcic force-pushed the feature/telemetry branch from 86aadfa to 7305c88 Compare May 5, 2026 09:03

asbjornu reviewed May 5, 2026

View reviewed changes

arturcic force-pushed the next/v7 branch from f84899d to 38a0121 Compare May 19, 2026 11:17

arturcic force-pushed the feature/telemetry branch from 7305c88 to 9f68dc6 Compare May 19, 2026 11:19

arturcic force-pushed the feature/telemetry branch 5 times, most recently from 802d361 to af891e1 Compare July 2, 2026 15:53

arturcic force-pushed the next/v7 branch from 38a0121 to 90b81f2 Compare July 2, 2026 16:07

arturcic force-pushed the feature/telemetry branch from af891e1 to da288b6 Compare July 3, 2026 16:52

arturcic force-pushed the feature/telemetry branch 8 times, most recently from f59a718 to c2dc611 Compare July 17, 2026 12:11

arturcic and others added 19 commits July 17, 2026 18:48

docs(git): add the managed-git migration research and plan

fcc2b83

Research and phased plan for replacing LibGit2Sharp with a vendored managed reader plus git CLI writes (GitTools#5031). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(git): add pack, pack-index, delta, and multi-pack-index readers

b912dbb

Packfile access with idx v2 lookup, ofs/ref delta stream application, a bounded pack memory cache with refcounted views, and multi-pack-index support. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(git): add commit, tree, and annotated-tag object parsers

f89fb8d

Author/committer signatures with commit-encoding handling, streaming tree reads for diff traversal, and annotated-tag target resolution. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

feat(git): add the object store over loose and packed objects

9c218cb

Single lookup facade across loose objects, packs, and the multi-pack index, with SHA-256 repository detection failing fast with a clear message. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ci: run the unit-test matrix against both git backends

5953f5b

Adds the git_backend dimension so every leg runs with libgit2 and managed, publishing per-backend test summaries and coverage. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: document the git backend selection and v7 defaults

2a72c1a

GITVERSION_GIT_BACKEND usage, the v7.0 libgit2 default and v7.1 managed flip, and the git-on-PATH requirement scoped to normalization scenarios. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

chore(ide): add JetBrains run configurations for CLI and backends

3fe5212

Add shared IntelliJ/Rider run configurations to facilitate debugging the CLI using both libgit2sharp and managed git backends.

feat(cli): add telemetry collection with opt-out controls

d5f4905

Implement a telemetry pipeline to collect redacted CLI usage data for OSS design decisions. Users can opt out via environment variables `DO_NOT_TRACK`, `GITVERSION_TELEMETRY_OPTOUT`, or the `--telemetry-opt-out` flag.

feat(telemetry): timebox data collection to 3 months post-release

a03ec43

Embed release dates in assembly metadata during build and disable telemetry if the window has expired or metadata is missing.

feat(telemetry): include CI provider and invocation source in payload

e4705ad

Detect the current CI environment and identify whether the CLI was invoked directly or via GitVersion.MsBuild to better understand usage patterns.

refactor(telemetry): move telemetry related files to a dedicated subf…

b08210a

…older Organize the GitVersion.App project structure by grouping telemetry components into their own directory.

refactor(telemetry): simplify type references by removing redundant n…

373b37c

…amespaces Remove fully qualified names for build agent interfaces and assembly reflection types to improve code readability.

arturcic force-pushed the feature/telemetry branch from c2dc611 to 373b37c Compare July 17, 2026 15:49

arturcic force-pushed the next/v7 branch from 2047d2d to 9878025 Compare July 17, 2026 15:50

		@@ -0,0 +1,163 @@
		using System.Globalization;

		namespace GitVersion;

	public static bool TryGetReleaseDate(Assembly assembly, out DateOnly releaseDate)
	public static bool TryGetReleaseDate(Assembly assembly, out TelemetryReleaseDate releaseDate)

	public static bool IsWithinWindow(DateOnly releaseDate, DateOnly utcToday) =>
	public bool IsWithinWindow(DateOnly utcToday) =>

	internal static class TelemetryReleaseDate
	internal class TelemetryReleaseDate


		public void AddFlag(string name) => AddValues(name, ["true"]);

		public void AddValue(string name, string? value, TelemetryValueKind kind = TelemetryValueKind.Plain)

	public void AddValues(string name, IEnumerable<string>? values, TelemetryValueKind kind = TelemetryValueKind.Plain)
	public void AddValues(string name, IEnumerable<string>? values)

Uh oh!

Conversation

arturcic commented Apr 29, 2026

Description

Related Issue

Motivation and Context

How Has This Been Tested?

Screenshots (if appropriate):

Checklist:

Uh oh!

arturcic commented Apr 29, 2026

Uh oh!

asbjornu left a comment

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

asbjornu May 5, 2026

Choose a reason for hiding this comment

Uh oh!

arturcic commented May 5, 2026

Uh oh!

HHobeck commented May 5, 2026

Uh oh!

asbjornu commented May 6, 2026

Uh oh!

arturcic commented May 6, 2026

Uh oh!

HHobeck commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gep13 commented May 7, 2026

Uh oh!

gep13 commented May 7, 2026

Uh oh!

gep13 commented May 7, 2026

Uh oh!

arturcic commented May 7, 2026

Uh oh!

arturcic commented May 7, 2026

Uh oh!

arturcic commented May 7, 2026

Uh oh!

arturcic commented May 7, 2026

Uh oh!

sonarqubecloud Bot commented May 19, 2026

Quality Gate passed

Uh oh!

HHobeck commented May 19, 2026

Uh oh!

sonarqubecloud Bot commented Jul 17, 2026

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

HHobeck commented May 7, 2026 •

edited

Loading