Buf Docs

Appearance

Bot users ​

Bot users are BSR accounts that exist to hold API tokens for automated workflows. They let you issue and revoke credentials for CI pipelines, scripts, and service integrations without tying those credentials to a human account or to your SSO provider. Only BSR administrators can create and manage them.

Bot users are available on self-hosted and dedicated BSR instances.

When to use a bot user ​

  • A CI job needs to run buf push, buf build, or another authenticated command against the BSR.
  • You want an automation’s permissions to be revocable independently of any employee’s account.
  • Your BSR is behind SSO, and SSO-provisioned accounts can’t own long-lived tokens suitable for machine use.

Create a bot user ​

  1. Go to the admin panel for your BSR instance and select Bot Users in the left-side menu. For example, if your BSR is https://buf.example.com, the page is at https://buf.example.com/admin/bot-users.
  2. Click Create bot user and enter a username.
  3. Click the new user’s name to open its details page, then create an API token. Copy the token value when it’s shown: the BSR doesn’t display it again.

A bot-user token has the same capabilities as a regular user token, subject to the limitations below.

Use a bot-user token ​

Set the token as the BUF_TOKEN environment variable in whatever environment runs Buf commands:

sh
export BUF_TOKEN=<bot-user-token>
buf push

In CI, store the token as a secret and inject it as BUF_TOKEN for the relevant steps.

Grant roles ​

A new bot user isn’t a member of any organization or repository and has no permissions until you assign it a role. Add the bot user to the organizations and repositories it needs access to, with the minimum role required for its tasks. See Roles for the available roles and what each one allows.

Limitations ​

Bot users differ from regular users in two ways:

  • They can’t sign in to the BSR web interface. A bot-user API token can’t be exchanged for a browser session cookie.
  • They can’t manage their own tokens. A BSR administrator creates, rotates, and revokes tokens on the bot user’s behalf.