Getting Started

BuildButler supports three deployment models.

Cloud

BuildButler manages the backend for you. CI systems send build data to api.buildbutler.dev and you view results at app.buildbutler.dev.

By default, BuildButler provisions a shared database. If you want full data ownership, you can connect your own Postgres instance under Settings → Database — BuildButler will use it instead.

Step 1 — Create your account

Sign up at app.buildbutler.dev/login.

Step 2 — Generate an API key

Go to Settings → API Keys and create a new key. You'll need this when connecting your CI system.

Step 3 — Connect your CI system

See Step 3 in the self-hosted guide — the integration options are identical. The only difference is your API endpoint is https://api.buildbutler.dev.

Step 4 — (Optional) Bring your own database

Go to Settings → Database and enter the connection string for any accessible Postgres instance. BuildButler will migrate and use it going forward.

Self-Hosted

Run the BuildButler server on your own infrastructure. All CI integrations work the same way — they just point to your server instead of api.buildbutler.dev.

See the Self-Hosted Installation guide for full setup instructions including Docker Compose, SSL, and configuration options.

Step 1 — Run the server

Docker

docker run -d \
  --name buildbutler \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://user:password@your-db-host/buildbutler" \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e BUILDBUTLER_LICENSE_KEY="BB-XXXX-XXXX-XXXX-XXXX" \
  ghcr.io/buildbutler/buildbutler:latest

npm

npm install -g @buildbutler/server
buildbutler

The server starts at http://your-server:3000. Open it in a browser and register your first account.

Step 2 — Generate an API key

Go to Settings → API Keys and create a new key. You'll use this when connecting your CI system.

Step 3 — Connect your CI system

Every integration needs to know two things: your server URL and your API key. The server URL is http://your-server:3000 (or your HTTPS domain if behind a reverse proxy).

Plugin-based (Jenkins, TeamCity) — install the plugin into your CI server and set the Server URL to your BuildButler instance. No per-pipeline changes needed.

• Jenkins setup guide
• TeamCity setup guide

CLI reporter (@buildbutler/ci) — add one step to your pipeline YAML. Set API_URL to your server and API_KEY to your key:

# GitHub Actions example
- uses: buildbutler/ci-action@v1
  with:
    api-url: http://your-server:3000
    api-key: ${{ secrets.BUILDBUTLER_API_KEY }}

Webhooks — register a webhook pointing at your server instead of api.buildbutler.dev. For example, a GitHub org webhook would be:

http://your-server:3000/webhooks/github?apiKey=YOUR_API_KEY

CI setup guides:

• GitHub Actions
• GitLab CI
• Buildkite
• Azure DevOps

Step 4 — Configure your workspace

• Notifications — Slack and email alerts for build failures
• JIRA — tag failures with JIRA tickets and see live ticket status
• AI Provider — enable natural language queries over your build data

Jenkins Self-Contained

The Jenkins Local plugin is a fully self-contained option for Jenkins users. It stores all CI data in your own PostgreSQL database and surfaces analytics directly inside the Jenkins UI — no external services, no internet required.

Step 1 — Provision a PostgreSQL database

Set up a Postgres 13+ instance that your Jenkins server can reach. Any hosting works — self-hosted, RDS, Cloud SQL, etc.

Step 2 — Download the plugin

Download the Jenkins Local .hpi from the Downloads page.

Step 3 — Install and configure

Install the .hpi in Jenkins (Manage Jenkins → Plugins → Advanced → Deploy Plugin), then go to Manage Jenkins → BuildButler and enter your database connection string.

See the Jenkins Local setup guide for full instructions.