Log grim in to GitHub

$ grim auth:login

Almost everything grim fetches is private: modules, themes, the base images on GHCR. On a new machine this is the first command after the install. You come back to it when a token has expired, when a pull from ghcr.io starts answering 403, or on the day you begin releasing and need write:packages.

If you already use the GitHub CLI there is nothing to paste. Your gh login is your identity, and grim borrows the token from it.

Usage

$ grim auth:login                     # take the token gh already holds
$ grim auth:login --packages-write    # the same, plus the scope for pushing images
$ grim auth:login --token=ghp_xxx     # a personal access token, no questions
$ grim auth:login --no-gh             # ignore gh and ask for a token

It runs from anywhere. Have Docker running, or the last step cannot log it in.

Arguments and options

Authenticate with GitHub through gh (or a Personal Access Token)

Usage

grim auth:login [-t|--token TOKEN] [--packages-write] [--no-gh] [--quiet-pipeline]

Options

What it actually does

Each step is printed with a ✓ or a !, and the run ends with OK Authenticated as <user>.

1. Finds a token. --token is taken as it is. Otherwise grim asks gh for the one it holds. When gh is not installed, not logged in, or ruled out with --no-gh, grim prints a link to GitHub's new-token page with the scopes filled in and waits for you to paste. The input is hidden.
2. Tops up the scopes. Only on the gh path. grim needs repo and read:packages, and write:packages with --packages-write. For what is missing it runs gh auth refresh -s <scope>, which opens the browser. Your existing login stays, and a broader scope counts: write:packages covers read:packages.
3. Validates the token. GitHub is asked who the token belongs to. A rejected token stops the run with Authentication failed: GitHub rejected the token (invalid or scope issue) and nothing is saved.
4. Saves it to ~/.grim/config.json. Token, user name and the time, with 0600 permissions. Other keys in the file are kept.
5. Writes Composer's global auth.json. The token goes under github-oauth, so composer install can clone private repositories. Other entries are kept.
6. Runs docker login ghcr.io. The token is passed on standard input, never as an argument. On WSL2 grim first removes a "credsStore": "desktop" entry from ~/.docker/config.json and says so, because that helper fails when called from inside WSL2.

--quiet-pipeline hides the steps and prints only the last line. The install scripts use it.

Pitfalls

A fine-grained token cannot pull from GHCR

GHCR does not accept fine-grained tokens, even when GitHub itself validates them. On the token path use a classic token with repo, read:user, read:packages, and write:packages if you release. The link grim prints has them selected.

Exit code 0 does not mean Docker is logged in

Some auth-pipeline steps failed (see above). grim-cli will work for GitHub-only operations. means the token is valid and saved, but the Composer or the Docker step failed, and the command still exits with success. The usual cause is a Docker daemon that is not running. Start it and run the login again.

Scopes grim cannot read are taken as fine

When gh does not report the scopes of its token, grim does not send you through a refresh on a guess. If a pull fails with 403 afterwards, run gh auth refresh -s read:packages yourself, then grim auth:login once more.

After it finishes

Three tools now share one token. grim auth:whoami shows what grim stored, and grim doctor shows the same line among the rest of the machine's checks.

Questions

How do I log out?

There is no logout command. grim config remove github_token takes the token out of grim's own file. Composer and Docker keep their copies until you remove them there, for Docker with docker logout ghcr.io.

Which token does a CI job use?

Export GRIM_GITHUB_TOKEN. It wins over the stored token and nothing is written to disk, which suits a short-lived token on a runner.

Related spells

Recipes that use it