Generate your radar

Open GitHub's token form

Press Open GitHub's token form. GitHub opens New fine-grained personal access token with the name velocity-radar-count, a description and an expiry 7 days away already filled in. Check that Resource owner is your own account.

Choose which repositories it can read

Under Repository access, choose All repositories. The count then covers everything you own, so no repository is left out by choice. Only select repositories also works, for up to 50. Either way the token can only read.

Check the permissions

Under Permissions, the Repositories list shows two lines: Contents: Read-only and Metadata: Read-only, which GitHub adds by itself. Nothing else is needed. If Contents is missing, press Add permissions, choose Contents and set it to Read-only.

Generate the token

Press Generate token, then Generate token again in the box that asks you to confirm. The box lists the same two permissions, both Read-only, and the expiry date.

Copy the token

GitHub shows the token once, starting with github_pat_. Press the copy button beside it and keep this tab open until the next step is done.

The token never reaches Velocity Radar. It stays in your GitHub account, and the code uses it on GitHub's machines inside that account.

Save it as an Actions secret named VELOCITY_RADAR_TOKEN

Press Open the new-secret page: it opens Settings → Secrets and variables → Actions → New repository secret in your repository. Type VELOCITY_RADAR_TOKEN as the name, paste the token as the secret, and press Add secret. VELOCITY_RADAR_TOKEN then appears under Repository secrets.

A public repository uses no private-repository Actions minutes.

Create the caller file

The caller file does one thing: it runs our counting code, count.yml, fixed at commit 33e9936, in your account. You can read that code before you commit anything. Its first 27 lines say in plain words what it asks GitHub for and what leaves your account: nothing. Most of the rest is our formulas file and its test cases, copied in full.

Press Create the file on GitHub, filled in. GitHub opens its editor with the name .github/workflows/velocity-radar-count.yml and the text below already in it.

Before you commit, check two lines. Line 8 ends count.yml@33e993618d8583e7aa329422aac458e85be8d73b # v7, and line 12 reads VELOCITY_RADAR_TOKEN: ${{ secrets.VELOCITY_RADAR_TOKEN }}. If either differs, your browser showed an older copy of this page: reload it and press the button again.

Then commit. Press Commit changes… at the top right, leave Commit directly to the default branch selected in the box that opens, and press Commit changes. The file then appears in the repository under .github/workflows.

If the editor opens empty, copy this text into it:

name: Velocity Radar count
on: workflow_dispatch
permissions:
  contents: read
  id-token: write
jobs:
  count:
    uses: AIMLPM/velocity-radar-count/.github/workflows/count.yml@33e993618d8583e7aa329422aac458e85be8d73b # v7
    with:
      timezone: America/Los_Angeles
    secrets:
      VELOCITY_RADAR_TOKEN: ${{ secrets.VELOCITY_RADAR_TOKEN }}

In the last line, the left side is the name the counting code reads and the right side is the secret you created; both are VELOCITY_RADAR_TOKEN.

The uses: line pins the counting code to its full commit id; the # v7 after it names that release, so Dependabot can offer the next one (the next step). The two timezone lines are optional. GitHub reports commit times in UTC, so the day, evening and overnight split needs your clock; put your own zone there. Use a region name such as Europe/Berlin, not an offset such as UTC+2, because offsets do not follow clock changes. Delete both lines and the other results remain.

Add the Dependabot file

Your caller file is pinned to one release of the count, so a new release never reaches your account by itself. This second file asks GitHub's Dependabot to tell you about each new release with a pull request in your repository; nothing changes until you merge it. Press Create it on GitHub, filled in, then Commit changes… and Commit changes, the same way as the caller file.

If the editor opens empty, copy this text into it:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Dependabot then looks once a week. It looks at every workflow in the repository, so it also offers updates for any other actions you use there.

If GitHub says a file with the same name already exists, you use Dependabot already. Open your .github/dependabot.yml instead, and if it has no github-actions entry, add these four lines at the end of its updates: list, lined up with the entries already there:

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Run it

Press Open the workflow page. Press Run workflow, then the green Run workflow in the menu that opens. A new run appears at the top of the list within a few seconds. It runs only when you press that button.

Read your totals

Open the run after a few minutes. Its summary shows 30, 90, 180 and 365-day totals for commits, substantive, merges, automated, micro, and median lines per substantive commit. It also shows longest runs, the day, evening and overnight split, commit size across all selected repositories against public ones, job_workflow_sha, and runner_environment. The figures appear in the run summary. The run sends nothing, so nothing leaves your account; press Check my run below and Velocity Radar reads them from the run, gives you a receipt, and your velocity.id8.one/stats page shows them while your snippet is on your profile.

The two notices at the bottom, about ubuntu-latest moving to Ubuntu 26, are GitHub's own and can be ignored.

Anyone can open this run, because the repository is public. Besides those tables, the summary shows how many repositories were read, how many of them are private and how many could not be read. The second job's log holds the same totals in packed form, including your totals for each day of the last two years. No repository names, commit ids, message text, files or code appear anywhere in the run. To take the run down once you have read it, choose then delete the run under Choose where to run it.

Anyone can open this run until you delete it in the next step, because the repository is public. Besides those tables, the summary shows how many repositories were read, how many of them are private and how many could not be read. The second job's log holds the same totals in packed form, including your totals for each day of the last two years. No repository names, commit ids, message text, files or code appear anywhere in the run.

Delete the run

Open the run, press … at the top right, beside Re-run all jobs, choose Delete workflow run, and confirm. The run, its summary and its logs are gone; the list of runs no longer shows it. Deleting cannot take back what someone saw before, and each rerun needs deleting again.

Remove the token

Delete it now rather than wait for it to expire, and make a new 7-day token for a later count. The caller file can stay: without a valid token it can do nothing, and it never runs by itself.