Skip to content

Commit 8470cf6

Browse files
williammartinCopilothubwritermxie
authored
Add GitHub CLI telemetry documentation page (#60892)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: hubwriter <hubwriter@github.com> Co-authored-by: Melissa Xie <mxie@users.noreply.github.com>
1 parent c00214c commit 8470cf6

2 files changed

Lines changed: 132 additions & 0 deletions

File tree

‎content/github-cli/github-cli/github-cli-telemetry.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: GitHub CLI telemetry
3+
intro: '{% data variables.product.prodname_cli %} sends pseudonymous telemetry to help improve the product. Learn what data is collected and how to opt out.'
4+
versions:
5+
fpt: '*'
6+
ghes: '*'
7+
ghec: '*'
8+
contentType: concepts
9+
category:
10+
- Learn the basics
11+
---
12+
13+
## Why {% data variables.product.prodname_cli %} collects telemetry
14+
15+
As agentic adoption of {% data variables.product.prodname_cli %} grows, visibility into how features are used in practice helps {% data variables.product.github %} improve the product. Telemetry data helps us prioritize development work and evaluate whether features meet real user needs.
16+
17+
For example, when a new subcommand is shipped, telemetry reveals whether anyone is using it and how. If adoption is low, that signals a need to revisit the feature's discoverability or design. If a subcommand sees high usage with certain flags, that shows where to invest in a better experience.
18+
19+
> [!IMPORTANT]
20+
> Telemetry data is not collected when the target is {% data variables.product.prodname_ghe_server %} or the user has authenticated {% data variables.product.prodname_cli %} with a {% data variables.product.prodname_ghe_server %} host.
21+
22+
## Reviewing telemetry
23+
24+
{% data variables.product.prodname_cli %} is open source. You can review the telemetry implementation in the [cli/cli](https://github.com/cli/cli) repository. If you want to see exactly what would be sent without actually sending it, you can enable logging mode using either an environment variable or a configuration option.
25+
26+
**Environment variable:**
27+
28+
```shell
29+
export GH_TELEMETRY=log
30+
```
31+
32+
**CLI configuration:**
33+
34+
```shell
35+
gh config set telemetry log
36+
```
37+
38+
In logging mode, the JSON payload that would normally be sent is printed to stderr instead. This lets you inspect every field before deciding whether to keep telemetry enabled. For example:
39+
40+
```shell
41+
GH_TELEMETRY=log gh skill install github/awesome-copilot git-commit --agent github-copilot --scope project
42+
```
43+
44+
This prints something like:
45+
46+
```text
47+
Telemetry payload:
48+
{
49+
"events": [
50+
{
51+
"type": "skill_install",
52+
"dimensions": {
53+
"agent": "",
54+
"agent_hosts": "github-copilot",
55+
"architecture": "arm64",
56+
"ci": "false",
57+
"device_id": "1e9a73a6-c8bd-4e1e-be02-78f4b11de4e1",
58+
"github_actions": "false",
59+
"invocation_id": "96d4862f-26c9-4385-961d-d749ae519c81",
60+
"is_tty": "true",
61+
"os": "darwin",
62+
"repo_visibility": "public",
63+
"skill_host_type": "github.com",
64+
"skill_names": "git-commit",
65+
"skill_owner": "github",
66+
"skill_repo": "awesome-copilot",
67+
"timestamp": "2026-04-24T11:54:51.057Z",
68+
"upstream_source": "none",
69+
"version": "2.91.0"
70+
}
71+
},
72+
{
73+
"type": "command_invocation",
74+
"dimensions": {
75+
"agent": "",
76+
"architecture": "arm64",
77+
"ci": "false",
78+
"command": "gh skill install",
79+
"device_id": "1e9a73a6-c8bd-4e1e-be02-78f4b11de4e1",
80+
"flags": "agent,scope",
81+
"github_actions": "false",
82+
"invocation_id": "96d4862f-26c9-4385-961d-d749ae519c81",
83+
"is_tty": "true",
84+
"os": "darwin",
85+
"timestamp": "2026-04-24T11:54:51.057Z",
86+
"version": "2.91.0"
87+
}
88+
}
89+
]
90+
}
91+
```
92+
93+
Some commands may include additional telemetry dimensions based on the context. In this example, the `skill_` fields are included because the `repo_visibility` is `public`.
94+
95+
> [!NOTE]
96+
> This command can only log telemetry for the exact command and context in which it ran. Changing environment variables or authenticated accounts may change the events and event dimensions included in the payload.
97+
98+
## How to opt out
99+
100+
You can opt out of the telemetry you see in the `log` mode described above using either an environment variable or a configuration option.
101+
102+
**Environment variables:**
103+
104+
```shell
105+
export GH_TELEMETRY=false
106+
```
107+
108+
Any falsy value works: `0`, `false`, `disabled`, or an empty string. You can also use the `DO_NOT_TRACK` convention:
109+
110+
```shell
111+
export DO_NOT_TRACK=true
112+
```
113+
114+
**CLI configuration:**
115+
116+
```shell
117+
gh config set telemetry disabled
118+
```
119+
120+
> [!NOTE]
121+
> The environment variables take precedence over the configuration value.
122+
123+
## Where data is sent
124+
125+
Telemetry events are sent to {% data variables.product.company_short %}'s internal analytics infrastructure. For more information about how {% data variables.product.company_short %} handles your data, see [AUTOTITLE](/free-pro-team@latest/site-policy/privacy-policies/github-general-privacy-statement).
126+
127+
## Additional information
128+
129+
{% data variables.product.prodname_cli %} allows you to add features to the product by installing {% data variables.product.company_short %}-authored and third-party extensions, including agents. These extensions may collect their own usage data and are not controlled by opting out. Consult the specific extension's documentation to learn about its telemetry reporting and whether it can be disabled.
130+
131+
This page describes client-side data collection for {% data variables.product.prodname_cli %} (`gh`). It does not apply to {% data variables.product.prodname_copilot %} or {% data variables.copilot.copilot_cli %}, which handle data collection separately. For information on the {% data variables.copilot.copilot_cli %}, see [AUTOTITLE](/free-pro-team@latest/copilot/concepts/agents/copilot-cli/about-copilot-cli) and [AUTOTITLE](/free-pro-team@latest/copilot/responsible-use/copilot-cli).

‎content/github-cli/github-cli/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ children:
1212
- /using-multiple-accounts
1313
- /creating-github-cli-extensions
1414
- /using-github-cli-extensions
15+
- /github-cli-telemetry
1516
- /github-cli-reference
1617
---
1718

0 commit comments

Comments
 (0)