The token
Everything here is read access. The collector never writes to GitHub. What varies is how much of the account a given token is allowed to see, and a handful of scopes are worth understanding rather than just granting.
Creating one
Section titled “Creating one”-
Go to
https://github.com/settings/tokens. -
Choose the kind of token and give it the scopes below.
repo,read:packages,read:user,read:org,security_events,read:public_keyandread:gpg_keycovers everything this collects.Read access to the repositories, including the repository permission Administration, which traffic needs, plus the account permissions for followers, gists, packages, plan, Git SSH keys and GPG keys.
-
Put it where the process can read it, and nowhere else.
Terminal window export GITHUB_TOKEN=github_pat_...The configuration file refers to it as
${GITHUB_TOKEN}, which is expanded from the environment at start-up. That is what lets the file be committed while the token stays out of it.
What each scope buys
Section titled “What each scope buys”| Scope | Without it |
|---|---|
| Push access to the repository, and Administration (read) on a fine-grained token | Traffic is a 403. GitHub shows views and clones only to someone who can push to the repository |
security_ | Dependabot and code scanning alerts look exactly like a repository with the feature switched off |
read: | The container registry is invisible. Package versions cost one call per package |
read: | Followers, contributions, gists and social accounts are missing |
read: | Repositories owned by an organisation are not discovered |
read:public_key, read:gpg_key | The keys family writes nothing, and says nothing. No other scope implies either |
Traffic is the one that surprises people, because being able to read a repository is not enough. GitHub shows views and clones only to someone who can push to the repository, and a fine-grained token also needs the repository permission Administration (read); a token that lacks either gets a 403 for that repository. The collector records that as “unavailable” and moves on, which is why the symptom is an empty traffic panel rather than a failed sweep.
Why the automatic GITHUB_TOKEN is not enough
Section titled “Why the automatic GITHUB_TOKEN is not enough”A workflow gets a GITHUB_TOKEN for free. It is not enough for this, and the
reason is worth being specific about rather than letting someone discover it as
an empty dashboard.
- It cannot read traffic, not even its own. Traffic needs push access to every repository being collected, and the automatic token has it only for the repository the workflow is running in. Even there it gets a 403: GitHub also asks for the repository permission Administration, which a workflow cannot grant its automatic token.
- It has no
security_events. Dependabot and code scanning alerts are invisible to it. - It has no
read:packages. The container registry is invisible to it. - It is not a user. Everything account-wide (followers, the contribution calendar, billing, notifications, the stars you gave) is about the person, not about a repository, and the automatic token is an installation, not a person.
So a workflow needs a personal access token stored as a repository secret and
passed in as the token input. See
GitHub Actions.
Running without a token
Section titled “Running without a token”Only for the three commands that ask GitHub nothing: -backfill-status,
-publish-dashboard and -uninstall. Everything that collects, a card of
public numbers included, needs one, and without it stops at start-up with
github.token is empty and GITHUB_TOKEN is unset. What a token short of a
scope costs is the table above: the part it cannot see is left empty, and the
log says not available (403) for each of them, which is the collector
reporting a permission, not a failure.