Updates, and no telemetry

The Ghostbranch program has no telemetry. It sends no usage data, no crash reports and no analytics, to us or to anyone. The only request it makes that you didn’t ask for is a look for a newer release, and it sends nothing about you.

The update check

Now and then, Ghostbranch asks GitHub whether a newer release is out, so it can remind you to upgrade. Upgrading Ghostbranch shows the reminder and what to do with it. This section is about what the look sends.

What it sends

One look is at most two requests, both to GitHub’s public API:

1. GET https://api.github.com/repos/ghostbranch-labs/ghostbranch/releases/latest, for the newest release.
2. Only when that release is newer than yours: GET https://api.github.com/repos/ghostbranch-labs/ghostbranch/security-advisories?state=published&per_page=100, to see whether it fixes a security issue in your version.

Ghostbranch sets three headers on each: User-Agent: ghostbranch, with no version and no operating system, and two that pick GitHub’s JSON format and API version (Accept and X-GitHub-Api-Version). The others are the ones any HTTP client sends, such as Host. There’s no token, no cookie, and no ID. Nothing in the request names you, your machine, your repos or your version: your version is compared with the answer on your machine. As with any request, GitHub sees the address it comes from.

Both requests together get 3 seconds; after that, the look gives up. They go through your proxy if you set HTTPS_PROXY, and never follow a redirect from https to plain http.

It never downloads or installs anything, and a failed look never makes a command fail.

When it looks

• In the background, while a command does its work. At the end, the command waits at most half a second for a look that hasn’t finished.
• Every 4 hours before version 1.0, and once a day from 1.0. In between, it uses what it saved last time.
• Not for help, shell completion, or guard check, which runs inside every git push.
• doctor looks every time, whatever the schedule, and shows the result on its last line.

What it keeps

The answer goes in update-check.json, at the top of GHOSTBRANCH_HOME. On macOS and Linux it’s readable by your user only (mode 0600). It holds:

• when it last looked, and why the last look failed, if it did;
• the newest version it saw, and that release’s page;
• the security advisories that affect your version;
• when it last reminded you, and when it last told an agent;
• the version of Ghostbranch that made the look.

Nothing in the file is sent anywhere. It’s a cache: delete it, and the next command looks again.

Turn it off

Set GHOSTBRANCH_NO_UPDATE_CHECK to any non-empty value, and Ghostbranch never looks:

Terminal

$ export GHOSTBRANCH_NO_UPDATE_CHECK=1

It’s also off, with nothing to set:

• in CI: whenever CI, GITHUB_ACTIONS, GITLAB_CI, BUILDKITE, CIRCLECI, JENKINS_URL or TF_BUILD is set;
• in a development build, made from a checkout of the source rather than downloaded as a release.

ghostbranch doctor says whether it’s on, and if not, why:

TerminalCopy

$ ghostbranch doctor

# the six checks, then:

update check: off (development build)

Warning

With the check off, Ghostbranch can’t tell you when a release fixes a security issue in your version. Watch the releases on GitHub instead.

This website

Once it’s live, this website may count page views anonymously: no cookies, and no personal data. Nothing is counted yet. That’s the website only. The Ghostbranch program you run sends nothing but the update check above.

Errors you may see

UPDATE_AVAILABLEwarningA newer Ghostbranch release is out (details.latest; this is details.current). details.security is true when it fixes a security issue that affects this version (details.advisories).

What to do

Tell the person, quoting details.upgrade (the command that upgrades this install) and, for a security fix, details.advisories. Never run the upgrade yourself. GHOSTBRANCH_NO_UPDATE_CHECK=1 turns the check off.