Sign inSign up
HomeGuidesManualsReference
Reference / Inputs
/

Authentication

Archives, Git repositories, and Buf image files can be read from remote locations. For those remote locations that need authentication, a couple mechanisms exist.

HTTPS

Remote archives and Buf image files use netrc files for authentication. buf looks for a netrc file at $NETRC first, defaulting to ~/.netrc. To learn how to log into the BSR see the getting started the tutorial.

Git repositories are cloned using the git command, so any credential helpers you have configured are automatically used.

Basic authentication can be also specified for remote archives, Git repositories, and Buf image files over HTTPS with these environment variables:

  • BUF_INPUT_HTTPS_USERNAME is the username. For GitHub, this is your GitHub user.
  • BUF_INPUT_HTTPS_PASSWORD is the password. For GitHub, this is a personal access token for your GitHub User.

Assuming one of these mechanisms is present, you can call buf as you normally would:

$ buf lint https://github.com/org/private-repo.git#branch=main
$ buf lint https://github.com/org/private-repo.git#tag=v1.0.0
$ buf lint https://github.com/org/private-repo/archive/main.tar.gz#strip_components=1
$ buf lint https://github.com/org/private-repo/archive/main.zip#strip_components=1
$ buf breaking --against https://github.com/org/private-repo.git#branch=main
$ buf breaking --against https://github.com/org/private-repo.git#tag=v1.0.0

SSH

Public key authentication can be used for remote Git repositories over SSH.

Git repositories are cloned via the git command, so by default, buf uses your existing Git SSH configuration, including any identities added to ssh-agent.

These environment variables can also be used:

  • BUF_INPUT_SSH_KEY_FILE is the path to the private key file.
  • BUF_INPUT_SSH_KNOWN_HOSTS_FILES is a colon-separated list of known hosts file paths.

Assuming one of these mechanisms is present, you can call buf as you normally would:

$ buf lint ssh://git@github.com/org/private-repo.git#branch=main
$ buf lint ssh://git@github.com/org/private-repo.git#tag=v1.0.0
$ buf breaking --against ssh://git@github.com/org/private-repo.git#branch=main
$ buf breaking --against ssh://git@github.com/org/private-repo.git#tag=v1.0.0

Note that CI services such as CircleCI have a private key and known hosts file pre-installed, so this should work out of the box.

  1. HTTPS
  2. SSH