The collector reads the repository where it is. What it sends: never whole files; facts and short excerpts of up to 120 characters where a check matched. It works with any git repository: GitHub, GitLab, Bitbucket, Azure DevOps, a self-hosted install of any of them, or one with no remote at all. Without a host to ask, the report has no stars, no language breakdown and no repository size: that is audience data rather than engineering data.

1. Sign in. Sign in with GitHub. No repository access is requested to sign in. Your account holds the Report key, the collector token and the report.
2. Add the Report key to your account. The collector spends a Report key your account holds: one bought with the email address you sign in with, or one added to it. Once signed in, add it under Report keys. To send the Report key to a target instead, leave it off your own account: a Report key can be added to one account only.
3. Make a collector token. Once signed in, make it under Collector tokens. The collector token is shown once, so copy it then.
4. Install or update the collector.

   pip install -U borehole

   Installed it with pipx? Update it with pipx upgrade borehole.
5. Give it your collector token. The collector token page shows steps 4 to 7 with your collector token filled in.

   export BOREHOLE_TOKEN=bh_…   # the collector token from step 3

6. See exactly what would be sent. In the repository's folder:

   borehole collect . --dry-run   # prints everything a survey would send, and sends none of it

   Read it. It is the whole of what leaves your machine, quoted lines included. You should not have to take our word for that.
7. Send it.

   borehole collect .   # sends the facts, then waits for the report

   This survey runs on your Report key. If it is the Report key's first, its 30 days start now.
8. Read the report. The collector prints the report's link when it is ready. The report is private to your account, and to anyone GitHub says controls the repository. Open the link signed in, or find it under Reports.

If the collector stops, it says why

• “This Python has no root certificates”: install them, then run the collector again. Nothing was sent.

  pip install certifi

  On a Mac with Python from python.org, running “Install Certificates.command” in its Applications folder also fixes it.
• “That collector token was not accepted”: make a new collector token (step 3) and set it again (step 5).
• “A collected survey needs a Report entitlement”: your account holds no Report key with days left. Add the Report key (step 2). Nothing was charged.
• “This collector token does not have the collect scope”: make a collector token with collect ticked (step 3).
• “Borehole now accepts 0.7.10 or later”: update the collector (step 4).

Someone else's private repository? The target runs these steps with your Report key. In your own Google Cloud instead? The same collector in a Confidential VM.