Skip to main content
Pullbase ships without default credentials. Use the bootstrap secret to create the first administrator, then manage users through the CLI, API, or web UI.
For a more detailed walkthrough of authentication and user management, see the CLI Guide.

​
Bootstrap workflow

1

Retrieve the bootstrap secret

docker compose exec central-server cat /app/secrets/bootstrap.secret
The secret is single-use. Copy it carefully and avoid storing it in plaintext documents.
2

Run the bootstrap command

docker compose exec central-server pullbasectl auth bootstrap-admin \
  --server-url http://localhost:8080 \
  --bootstrap-secret-file /app/secrets/bootstrap.secret \
  --username admin_user \
  --password 'ChangeMeNow123!'
The command returns a JSON payload containing a short-lived access_token. Test it immediately:
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  http://localhost:8080/api/v1/auth/me
3

Clean up

The server deletes the bootstrap secret file after a successful bootstrap. Remove any notes or terminals that still display the secret.

​
Bootstrap via environment variable

Alternatively, provide the bootstrap secret via environment variable instead of a file: 
environment:
  PULLBASE_BOOTSTRAP_SECRET: your-secret-here
This is useful in orchestrated environments where mounting files is inconvenient.

​
Managing users

​
CLI

pullbasectl users create \
  --server-url http://localhost:8080 \
  --admin-token $ADMIN_JWT \
  --new-username ops_user \
  --new-password 'StrongPassword!2024' \
  --role viewer
To delete a user, call DELETE /api/v1/users/{userID} or use the web UI. CLI deletion support is in development.

​
Web UI

  1. Sign in at http://localhost:8080 (or your production URL with TLS).
  2. Navigate to Settings → Users.
  3. Use Add user to provision new operators.
  4. Delete a user by clicking the trash icon and typing the username to confirm.
Pullbase prevents deleting the last active admin or your own account. Promote another admin before deactivating the original bootstrap user.

​
Authentication model

  • Admins/Users: Authenticate with username/password. The server issues JWT access tokens signed with PULLBASE_JWT_SECRET.
  • Agents: Authenticate with agent tokens scoped to a single server. Tokens are hashed at rest and shown only once at creation time. Prefixed with pbt_.
  • GitHub App: Uses App ID, private key, installation ID, and repository ID to mint short-lived installation tokens for agents.

​
Token lifetime

  • API tokens expire based on PULLBASE_JWT_EXPIRY_HOURS (default 24 hours).
  • Agent tokens can be set to expire (--expires-in when creating via CLI) or rotated manually.

​
Session management

  • The web UI stores the JWT in an HTTP-only cookie.
  • Sign out from the avatar menu or let the token expire naturally.
  • To revoke all sessions, rotate PULLBASE_JWT_SECRET and restart Pullbase (forces logout for every user).

​
User roles

RolePermissions
adminFull access: manage users, environments, servers, tokens
userManage environments and servers, view users
viewerRead-only access to all resources
Capture the bootstrap workflow and admin creation steps in your internal runbooks. In an incident you may need to redeploy Pullbase and bootstrap quickly.