Skip to content
Ghostbranchdocs
GitHub

Log in

Give Ghostbranch a GitHub token, by logging in with its GitHub App or by storing a token you already have.

Ghostbranch works through GitHub for you. It reads your public repo, pushes to the private shadow repo, and opens the pull request when you publish. For that it needs a GitHub token.

Log in with the GitHub App

Section titled “Log in with the GitHub App”

Run ghostbranch login in a terminal. It shows a short code and opens GitHub’s device page in your browser:

Terminal
ghostbranch login
To log in, open https://github.com/login/device and enter this code: WDJB-MJHT
(It is open in your browser.)
Waiting for you to approve it on GitHub. Ctrl-C cancels.
Logged in to GitHub as you with the Ghostbranch GitHub App (token expires 2026-10-12 15:15 UTC; it refreshes itself).
Next, pick the repos Ghostbranch may use (your public repo and its shadow): https://github.com/apps/ghostbranch-cli/installations/new

Enter the code on that page and approve. The first time, Ghostbranch then prints a link to install its GitHub app: open it, and pick your public repo and its shadow repo. The token can reach only the repos you pick.

The login is kept in your operating system’s keychain, never in a file. It refreshes itself, so you rarely log in again. If a command says LOGIN_EXPIRED, run ghostbranch login once more.

Use a token you already have

Section titled “Use a token you already have”

If you’d rather use a token of your own, pipe it to ghostbranch login --with-token. It reads the token from standard input, never from an argument, so it stays out of your shell history. It checks the token with GitHub, then stores it in the keychain. For example, to reuse the GitHub CLI’s login:

Terminal
gh auth token | ghostbranch login --with-token
Stored the oauth token for you in the OS keychain.

On a machine with no keychain, such as a headless Linux server, login stops with LOGIN_UNAVAILABLE. Set the GHOSTBRANCH_TOKEN environment variable there instead.

See which token is in use

Section titled “See which token is in use”

ghostbranch auth status says where the token comes from, whose it is, and whether it can publish to the repo you’re in:

Terminal
ghostbranch auth status
Token: from login, app token, you (valid: true)
Can publish to you/project: true
Stored login: you (app), token expires 2026-10-12 15:15 UTC, refreshable until 2027-04-12 07:15 UTC

An app token lasts a few hours, and Ghostbranch refreshes it when it runs out. The login itself keeps refreshing for six months; ghostbranch doctor warns two weeks before it ends.

Which token wins

Section titled “Which token wins”

Ghostbranch uses the first token it finds, in this order:

  1. GHOSTBRANCH_TOKEN, from the environment.
  2. Your stored login, from ghostbranch login.
  3. GH_TOKEN, then GITHUB_TOKEN, from the environment.
  4. The GitHub CLI’s token (gh auth token).

When GHOSTBRANCH_TOKEN is set, the stored login is never read. That is how you give a coding agent its own token: set GHOSTBRANCH_TOKEN in the agent’s environment only.

Log out

Section titled “Log out”

ghostbranch logout removes the stored login from the keychain:

Terminal
ghostbranch logout
Removed the stored GitHub login for you.
To revoke the app's access at GitHub too: https://github.com/settings/apps/authorizations

Logging out can’t revoke the app’s access at GitHub, so it gives you the page where you do that. Tokens in your environment, such as GHOSTBRANCH_TOKEN or GH_TOKEN, stay as they are.