Morning Board

Guides

A read-only GitHub token for a dashboard

A dashboard only needs to look. Here is how to give it a token that can read the repositories you choose and nothing else, and what each permission is for.

Last updated

Why a fine-grained token

GitHub has two kinds of personal access token. A classic token uses broad scopes: the repo scope that lets it see private pull requests also lets it push code and delete branches. A fine-grained token is limited to repositories you pick and to permissions you set one by one, each as read-only or read and write. For anything that only displays data, fine-grained is the right choice.

Create the token

  1. Open github.com/settings/personal-access-tokens/new. You can also reach it from Settings, Developer settings, Personal access tokens, Fine-grained tokens.
  2. Give it a name you will recognize later, such as Morning Board on my MacBook, and pick an expiration. Shorter is safer; you will need to paste a new token when it expires.
  3. Choose the resource owner: your own account, or an organization. See the note below; this choice matters.
  4. Under Repository access, choose Only select repositories and pick the ones you want on the board, or All repositories if you prefer.
  5. Under repository permissions, set the ones below to Read-only, leave everything else at No access, and generate the token. Copy it right away; GitHub shows it once.

What each permission is for

GitHub renames and regroups permissions from time to time. If a name here does not match what you see, pick the read-only permission whose description covers pull requests or CI. None of them ever needs Read and write.

If a pull request shows no CI mark in the widget while GitHub shows checks on it, the token is missing a permission that covers those checks. Edit the token on GitHub, add the missing read permission, and click refresh in the widget.

One owner per token

A fine-grained token can only reach repositories that belong to its resource owner. A token for your personal account cannot read an organization's private repositories, and a token for an organization cannot read your personal ones.

So if one login has both personal and organization repositories you care about, create one token per owner: one with your account as the resource owner, and one for each organization. In Morning Board, add each token as its own connection. They appear side by side, labelled with the organization, and a pull request both tokens can see is shown once.

If you use separate GitHub logins for personal and work, connect each login with its own token in the same way.

When a work organization has to approve it

Organizations can require an owner to approve fine-grained tokens before they can read organization repositories. Until then the request is pending, and Morning Board shows those repositories as Hidden by organization policy rather than failing. An organization owner approves the request in the organization's settings, under personal access tokens. Organizations can also cap how long a token may live, so the expiration you can pick may be shorter.

Where the token goes

Morning Board stores the token in your Mac's Keychain and sends it only to api.github.com. There is no Morning Board server. You can revoke the token on GitHub at any time; the widget then shows GitHub connection expired, click to reconnect for that account while your other accounts keep working.

More guides