github_token: Tools for handling GitHub personal access tokens (PAT)

In ghclass: Tools for Managing Classes on GitHub

Tools for handling GitHub personal access tokens (PAT)

Description

• github_get_token - returns the user's GitHub personal access token (PAT).

• github_set_token - defines the user's GitHub PAT by setting the GITHUB_PAT environmental variable. This value will persist until the session ends or gihub_reset_token() is called.

• github_reset_token - removes the value stored in the GITHUB_PAT environmental variable.

• github_test_token - checks if a PAT is valid by attempting to authenticate with the GitHub API.

• github_token_scopes - returns a vector of scopes granted to the token.

• github_token_sitrep - reports on the token: its type and source, the authenticated user, the granted scopes (flagging any that ghclass needs but are missing), and the API rate limit.

Usage

github_rate_limit()

github_graphql_rate_limit()

github_get_token()

github_set_token(token)

github_reset_token()

github_test_token(token = github_get_token())

github_token_scopes(token = github_get_token())

github_token_sitrep(token = github_get_token())

Arguments

token

Character. Either the literal token, or the path to a file containing the token.

Details

This package looks for the personal access token (PAT) in the following places (in order):

• Value of GITHUB_PAT environmental variable.

• A credential returned by gh::gh_token(), such as GITHUB_TOKEN, a token stored with gitcreds, or a Posit Connect viewer token.

For additional details on creating a GitHub PAT see the usethis vignette on Managing Git(Hub) Credentials. For those who do not wish to read the entire article, the quick start method is to use:

• usethis::create_github_token() - to create the token and then,

• gitcreds::gitcreds_set() - to securely cache the token.

Scopes

A classic PAT needs the repo and admin:org scopes for ghclass to manage an organization's repositories and teams, the workflow scope to add or modify files under ⁠.github/workflows/⁠, the notifications scope to use repo_watch(), repo_ignore(), and repo_unwatch(), and the delete_repo scope to use repo_delete(). Note that usethis::create_github_token() does not select admin:org by default. Fine-grained tokens do not report scopes, so github_token_sitrep() cannot check them. GitHub does not support fine-grained or GitHub App tokens for repo_watch(), repo_ignore(), or repo_unwatch().

Value

github_get_token() returns the current PAT as a character string with the gh_pat class. See gh::gh_token() for additional details.

github_set_token() and github_reset_token() return the result of Sys.setenv() and Sys.unsetenv() respectively.

github_test_token() invisibly returns a logical value, TRUE if the test passes, FALSE if not.

github_token_scopes() returns a character vector of granted scopes.

github_token_sitrep() invisibly returns a list with the token's type, source, API url, the authenticated user's login, the granted scopes (NULL when the token does not report them), the scopes ghclass uses that are missing, and rate limit details.

Examples

## Not run: 
github_test_token()

github_token_scopes()

github_token_sitrep()

(pat = github_get_token())

github_set_token("ghp_BadTokenBadTokenBadTokenBadTokenBadToken")
github_get_token()
github_test_token()

github_set_token(pat)

## End(Not run)

ghclass documentation built on Aug. 31, 2026, 5:08 p.m.