Environment Variables

All environment variables supported by BuildButler for configuring the collector, dashboard, and integrations.

BuildButler is configured primarily through environment variables. Set them in your .env file, Docker Compose, or CI/CD platform.

Core

Variable	Default	Description
`DATABASE_URL`	—	PostgreSQL connection string (required)
`PORT`	`3000`	HTTP server port
`HOST`	`0.0.0.0`	HTTP server bind address
`NODE_ENV`	`production`	`development` enables hot reload and verbose logging
`LOG_LEVEL`	`info`	One of `debug`, `info`, `warn`, `error`

Jenkins connection

Variable	Default	Description
`JENKINS_URL`	—	Base URL of your Jenkins instance
`JENKINS_USERNAME`	—	API username
`JENKINS_TOKEN`	—	API token
`JENKINS_POLL_INTERVAL`	`30`	Seconds between API polls
`JENKINS_TLS_REJECT_UNAUTHORIZED`	`true`	Set to `false` for self-signed certs
`JENKINS_MAX_BUILDS_PER_JOB`	`100`	Maximum builds to fetch per job on initial sync

Database

# Full connection string format
DATABASE_URL="postgresql://user:password@host:5432/buildbutler?sslmode=require"

Variable	Default	Description
`DB_POOL_MIN`	`2`	Minimum pool connections
`DB_POOL_MAX`	`10`	Maximum pool connections
`DB_MIGRATION_AUTO`	`true`	Run migrations on startup
`DB_RETENTION_DAYS`	`90`	Auto-delete builds older than this

Authentication

Variable	Default	Description
`AUTH_SECRET`	—	Secret for signing session tokens (required)
`AUTH_PROVIDER`	`local`	`local`, `oidc`, or `saml`
`OIDC_ISSUER`	—	OIDC provider issuer URL
`OIDC_CLIENT_ID`	—	OIDC client ID
`OIDC_CLIENT_SECRET`	—	OIDC client secret

Example `.env` file

# .env
DATABASE_URL=postgresql://bb:bb@localhost:5432/buildbutler
PORT=3000
LOG_LEVEL=info
AUTH_SECRET=change-me-to-a-random-string
 
JENKINS_URL=https://jenkins.example.com
JENKINS_USERNAME=ci-bot
JENKINS_TOKEN=11a2b3c4d5e6f
JENKINS_POLL_INTERVAL=30
 
DB_RETENTION_DAYS=90

Overriding at runtime

Environment variables can also be set per-connection in the dashboard under Settings → Connections → Advanced. Connection-level overrides take precedence over environment variables.