Type alias AuthCallback

Type declaration

• • (url: string, auth: Auth): Auth | void | Promise<Auth | void>

  • The callback allows to request credentials.

    Authentication is normally required for pushing to a git repository. It may also be required to clone or fetch from a private repository. Git does all its authentication using HTTPS Basic Authentication.

    Example

    await clone({
      ...,
      onAuth: url => {
        let auth = lookupSavedPassword(url)
        if (auth) return auth
        if (confirm('This repo is password protected. Ready to enter a username & password?')) {
          auth = {
            username: prompt('Enter username'),
            password: prompt('Enter password'),
          }
          return auth
        } else {
          return { cancel: true }
        }
      }
    })
    

    Option 1: Username & Password

    Return an object with { username, password }.

    However, there are some things to watch out for.

    If you have two-factor authentication (2FA) enabled on your account, you probably cannot push or pull using your regular username and password. Instead, you may have to use a Personal Access Token.

    Personal Access Tokens

    • Instructions for GitHub
    • Instructions for Bitbucket
    • Instructions for GitLab

    In this situation, you want to return an object with { username, password } where password is the Personal Access Token. Note that GitHub actually lets you specify the token as the username and leave the password blank, which is convenient but none of the other hosting providers do this that I'm aware of.

    OAuth2 Tokens

    If you are writing a third-party app that interacts with GitHub/GitLab/Bitbucket, you may be obtaining OAuth2 tokens from the service via a feature like "Login with GitHub". Depending on the OAuth2 token's grants, you can use those tokens for pushing and pulling from git repos as well.

    In this situation, you want to return an object with { username, password } where username and password depend on where the repo is hosted.

    Option 2: Headers

    This is the super flexible option. Just return the HTTP headers you want to add as an object with { headers }. If you can provide { username, password, headers } if you want. (Although if headers includes an Authentication property that overwrites what you would normally get from username/password.)

    To re-implement the default Basic Auth behavior, do something like this:

    const auth = {
      headers: {
        Authentication: `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`
      }
    }
    

    If you are using a custom proxy server that has its own authentication in addition to the destination authentication, you could inject it like so:

    const auth = {
      username,
      password,
      headers: {
        'X-Authentication': `Bearer ${token}`
      }
    }
    

    Parameters

    • url: string

    • auth: Auth

    Returns Auth | void | Promise<Auth | void>