Quickstart

Install GrantTrace, record one GitHub behavior, and commit your first permission contract.

Don't know what the fuck you're doing? You're in the right place. GrantTrace does one job: it watches your app talk to GitHub and writes down the permissions it actually used. Give it one command. It gives you a receipt.

Before you start

  • Node.js 22 or newer
  • a Node.js project with a package.json file
  • one test or script that makes your app perform a real GitHub action

No test command yet? Stop here. GrantTrace watches behavior. It does not invent it. Give your app a repeatable test or script first, then come back.

Find the right folder

Open a terminal in your app's folder. If you can see package.json, you're probably home.

Install GrantTrace

Terminal
npm install --save-dev granttrace@beta

If your project uses pnpm:

Terminal
pnpm add --save-dev granttrace@beta

Record one real scenario

Terminal
npx granttrace record issue-triage -- npm test -- issue-triage

That command has three useful pieces:

  • issue-triage is a short name you make up for the behavior being tested.
  • The -- is the fence. GrantTrace is on the left.
  • Your normal test command is on the right. Replace npm test -- issue-triage with yours.

GrantTrace runs the command, watches its GitHub REST requests, and prints what it saw. For pnpm projects, use pnpm exec granttrace and your normal pnpm test command instead.

Review and keep the receipt

The same command prints the permission, route, evidence, and attribution diff, then asks whether you want to accept that exact change. Read it. If it matches the behavior you just ran, type y. The default answer is no. This is the one bit you should not autopilot.

GrantTrace creates granttrace.lock.json. Commit it. That file is the useful bit: a reviewable record of the permissions this behavior used. The private scratch files in .granttrace/ stay local; GrantTrace adds that directory to .gitignore for you.

That's the full normal onboarding flow:

install → record → review → commit
How recording works

No source edit or separate initialization is required for the standard Node.js path. GrantTrace injects a preload into the child process and observes supported GitHub REST calls through Node's global fetch. Standard Octokit clients use that path automatically.

Automatic capture is restricted to requests targeting exactly https://api.github.com. Off-origin responses are ignored even if they include a permission-like header. The command after -- is passed as an argument array without a shell, and output streams to your terminal.

Recording the same scenario name again atomically replaces its previous local observation file. On the first recording, GrantTrace creates private .granttrace/ state before the test process can start. granttrace init remains available for explicit setup, while granttrace doctor is optional diagnostics.

In CI or another noninteractive terminal, GrantTrace never prompts or accepts. A changed contract exits 6. Review it locally, or use granttrace check followed by granttrace check --accept when you want review and acceptance as separate commands.

Add more scenarios

npx granttrace record release-read -- \
  npm test -- release-read
npx granttrace scenario list

Each successful recording solves one aggregate contract while preserving which scenario exercised each route.

Removing the final recording is also a reviewable contraction. After check --accept, the v3 contract has zero observed scenarios, routes, selected permissions, and unknowns. Validated manual keeps are retained until you remove them explicitly; zero observed coverage never turns a keep into proven necessity.

One honest limit

GrantTrace only knows what your command touched. Untested paths are still untested. No magic. No bullshit.

Next steps

Overview

See which GitHub App permissions each tested behavior actually uses.

Custom transports

Use explicit instrumentation when GrantTrace's automatic Node preload cannot observe your GitHub client.