Skip to content

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 remote repository, you will need to authenticate with the respective service.

This page covers methods to authenticate git-spice with GitHub, GitLab, and Bitbucket Cloud. Note that GitLab support requires at least version v0.9.0. Bitbucket Cloud support requires at least version Unreleased.

Logging in

Take the following steps to authenticate with a service:

  1. Run the following command:

    gs auth login

  2. Pick the service you want to authenticate with.

  3. You will be presented with a list of authentication methods. Pick the one that suits you best.

Tip

Skip prompt (2) by running gs auth login inside a Git repository cloned from GitHub or GitLab.

Authentication methods

Each supported service supports different authentication methods.

Read on for more details on each method, or skip on to Pick an authentication method.

OAuth

Supported by GitHub GitLab

With OAuth authentication, you will take the following steps:

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

On GitHub, OAuth is available in two flavors:

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

For more granular control than that, 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.

For Self-Hosted GitLab instances, an administrator will need to set up a git-spice OAuth App. Be sure to uncheck the "Confidential" option when creating the App.

If that is not an option, use a Personal Access Token.

GitHub App

Supported by GitHub

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.

Git Credential Manager

Supported by GitHub BitBucket

Git Credential Manager (GCM) is a secure credential storage system for Git. If you already have GCM configured for GitHub or Bitbucket, git-spice can reuse those credentials automatically.

To set up GCM:

  1. Install Git Credential Manager:

    brew install git-credential-manager

    Follow the instructions at https://github.com/git-credential-manager/git-credential-manager

  2. Configure Git to use GCM:

    git config --global credential.helper manager

  3. Push or pull from a GitHub or Bitbucket repository once. This triggers the OAuth flow in your browser.

After that, git-spice will use the stored OAuth token automatically.

Additionally, if you have GCM configured, git-spice will automatically fall back to GCM credentials when no other authentication token is available—even without running gs auth login.

API Token

Supported by BitBucket

Bitbucket API tokens provide a way to authenticate without using your main account password. To use an API token with git-spice:

  1. Go to https://bitbucket.org/account/settings/api-tokens/.
  2. Click "Create token".
  3. Enter a descriptive label.
  4. Select the following scopes:
    • pullrequest:write - create and edit pull requests
    • account - read workspace members for reviewer lookup
  5. Click "Create" and copy the generated token.

Personal Access Token

Supported by GitHub GitLab

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

The token may be a classic token or a fine-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 the following scopes: repo, read:org for full access to all repositories, or just 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
    • (v0.21.0 or higher) in the Organization permissions section, grant Read-only access to Members

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

To use a Personal Access Token with GitLab:

  1. Go to https://gitlab.com/-/user_settings/personal_access_tokens.
  2. Select Add new token

  3. In the token creation form:

    • pick a descriptive name for the token
    • pick an expiration date if needed
    • select the api scope

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

Service CLI

Supported by GitHub GitLab

If you have the GitHub or GitLab CLIs installed and authenticated, you can get authentication tokens for git-spice from them.

  1. Install the GitHub CLI

  2. Authenticate it:

  1. Install the GitLab CLI.

  2. Authenticate it:

Once you pick this authentication option, no additional steps are required. git-spice will request a token from the CLI as needed.

Environment variable

Supported by GitHub GitLab BitBucket

You can provide the authentication token as an environment variable. This is not recommended as a primary authentication method, but it can be useful in CI/CD environments.

Set the GITHUB_TOKEN environment variable to your token.

Set the GITLAB_TOKEN environment variable to your token.

Set the BITBUCKET_TOKEN environment variable to your OAuth token. This should be a Bearer token (OAuth access token).

If you have the environment variable set, this takes precedence over all other authentication methods.

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

Picking an authentication method

OAuth is best if you have the permissions needed to install it on all repositories that you want to use git-spice with. GitHub App is similar, but it may be preferable if you don't want to give git-spice access to all your repositories.

Git Credential Manager is convenient if you already have GCM installed for git operations. git-spice can reuse your existing GCM credentials automatically, and will fall back to them even without explicit login.

Service CLI is the most convenient method if you already have the GitHub CLI installed and authenticated. It loses security benefits of the other methods, as it re-uses the token assigned to the CLI.

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

OAuth is best if you have the permissions needed to install it on all repositories that you want to use git-spice with.

Service CLI is the most convenient method if you already have the GitLab CLI installed and authenticated. It loses security benefits of the other methods, as it re-uses the token assigned to the CLI.

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

Git Credential Manager integrates with Bitbucket's OAuth flow and handles token refresh automatically. This is convenient if you already have GCM installed for git operations.

API Token is flexible and secure. It requires manual token management but works without additional tools.

Environment variable is the least convenient and the least secure method. End users should typically never pick this. It is intended only for CI/CD environments where you have no other choice.

Self-hosted instances

GitHub Enterprise

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

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

Optionally, also set the GitHub API URL with the spice.forge.github.apiUrl configuration option. By default, the API URL is assumed to be at /api under the GitHub URL.

The GitHub API URL will typically end with /api, not /api/v3 or similar.

Alternatively, these configuration options may also be set with the GITHUB_URL and GITHUB_API_URL 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.

These must both be set for git-spice to work with GitHub Enterprise.

GitLab Self-Hosted

To use git-spice with a self-hosted GitLab instance, set spice.forge.gitlab.url to the address of your GitLab instance.

v0.13.0 Optionally, also set the GitLab API URL with the spice.forge.gitlab.apiUrl configuration option. By default, the API URL is the same as the GitLab URL.

Alternatively, set these configuration options with the GITLAB_URL and GITLAB_API_URL environment variables.

OAuth with GitLab Self-Hosted

To use OAuth authentication with a self-hosted GitLab instance, you must first set up an OAuth App on the GitLab instance. Be sure to uncheck the "Confidential" option when creating the App. This will generate an OAuth Client ID for the App.

Feed that into git-spice with the spice.forge.gitlab.oauth.clientID configuration option.

This may also be set with the GITLAB_OAUTH_CLIENT_ID environment variable.

Authenticate with gs auth login as usual after that.

Safety

By default, git-spice stores your 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