Authentication

git-spice is offline-first. It does not require authentication for local stacking operations. However, once you want to push or pull changes to/from a GitHub repository, you will need to authenticate with GitHub.

This page covers the authentication options for git-spice.

Logging in

To authenticate with GitHub, run:

gs auth login

This will present you with a list of authentication methods.

See Authentication methods for details on what to expect from each method, or skip on to Pick an authentication method.

Authentication methods

git-spice provides several ways to authenticate with GitHub.

OAuth

With OAuth authentication, you will take the following steps:

1. Authenticate yourself on github.com in your browser.
2. Authorize git-spice to act on your behalf on the current device only.

Two options are available for OAuth:

• OAuth: grants access to all repositories, public and private.
• OAuth: Public repositories only: grants access to public repositories only.

For more granular control, use GitHub App authentication.

Note

For private repositories owned by organizations, you will need a member with administrative access to the repository to allow installation of the git-spice OAuth App. If that is not an option, use a Personal Access Token.

GitHub App

With GitHub App authentication, you will take the following steps:

1. Authenticate yourself on github.com in your browser.
2. Authorize git-spice to act on your behalf on the current device only.
3. Install the git-spice GitHub App on the repositories you want to use git-spice with.

Important: Authentication alone does not grant any access. You must install the GitHub App to access repositories with git-spice.

Note

For private repositories owned by organizations, you will need a member with administrative access to the repository to allow installation of the git-spice GitHub App. If that is not an option, use a Personal Access Token.

Personal Access Token

To use a Personal Access Token with git-spice, you will generate a Personal Access Token on GitHub and enter it in the prompt.

The token may be a classic token or a fine-grained token.

Classic tokenFine-grained token

With classic tokens, you can grant access to all repositories, or all public repositories only. These tokens have the ability to never expire.

To use a classic token:

1. Go to https://github.com/settings/tokens/new. This may ask you to re-authenticate.

2. In the token creation form:

   • enter a descriptive note for the token
   • pick an expiration window, or select "No expiration"
   • select repo scope for full access to all repositories, or public_repo for access to public repositories only

3. Click "Generate token" and copy the token.

With fine-grained tokens, you have more granular control over repositories that you grant access to. These token must always have an expiration date.

To use a fine-grained token:

1. Go to https://github.com/settings/personal-access-tokens/new. This may ask you to re-authenticate.

2. In the token creation form:

   • pick a descriptive note for the token
   • pick an expiration window
   • in the Repository access section, select the repositories you want to use git-spice with
   • in the Repository permissions section, grant Read and write access to Pull requests and Contents

3. Click "Generate token" and copy the token.

After you have a token, enter it into the prompt.

GitHub CLI

If you have the GitHub CLI installed and authenticated, you can select this as the authentication method.

This requires no additional steps. We'll request a token from GitHub CLI as needed.

GITHUB_TOKEN

If you have a GITHUB_TOKEN environment variable set, that takes precedence over all other authentication methods.

The gs auth login operation will fail if you use this method.

Picking an authentication method

OAuth and GitHub App authentication are best if you have the permissions needed to install OAuth/GitHub Apps on all repositories that you want to use git-spice with. The two are equivalent in terms of user experience. Use GitHub App authentication if you don't want to give git-spice access to all your repositories.

GitHub CLI is the most convenient method if you already have the GitHub CLI installed and authenticated. It loses some security benefits of the other methods, as it re-uses the token from the GitHub CLI. You lose the ability to revoke the git-spice token without revoking the GitHub CLI token.

Personal Access Token is flexible and secure. It may be used even with repositories where you don't have permission to install OAuth/GitHub Apps. However, it requires manual token management, making it less convenient.

GITHUB_TOKEN is the least convenient and the least secure method. It is intended only for CI/CD environments where you have no other choice.

GitHub Enterprise

To use git-spice with a GitHub Enterprise instance, inform it of the instance URL, authenticate, and use git-spice as usual.

v0.4.0v0.3.1 or older

Set the spice.forge.github.url configuration option to the address of your GitHub Enterprise instance.

The GitHub API is assumed to be at /api under the GitHub URL. For example, if your GitHub Enterprise instance is at https://github.example.com, the API is assumed to be at https://github.example.com/api.

If this is not the case, set the spice.forge.github.apiUrl configuration option.

These values may also be set with environment variables.

Set the GITHUB_URL and GITHUB_API_URL environment variables to the address of your GitHub Enterprise instance and its API endpoint, respectively.

Both values must be set for git-spice to work with GitHub Enterprise.

Safety

By default, git-spice stores your GitHub authentication token in a system-specific secure storage. On macOS, this is the system Keychain. On Linux, it uses the Secret Service, which is typically provided by GNOME Keyring.

Since version v0.3.0, if your system does not provide a secure storage service, git-spice will fall back to storing secrets in a plain-text file at $XDG_CONFIG_HOME/git-spice/secrets.json or the user's configuration directory. If it does that, it will clearly indicate so at login time, reporting the full path to the secrets file.

Example