Getting Started

Follow these steps to get BuildButler running and connected to Jenkins.

Prerequisites

• Node.js 18 or later
• Docker (recommended) or a PostgreSQL 15+ instance
• A Jenkins instance with REST API access enabled

1. Install BuildButler

The fastest way to get started is with Docker Compose:

git clone https://github.com/buildbutler/buildbutler.git
cd buildbutler
cp .env.example .env
docker compose up -d

BuildButler will be available at http://localhost:3000.

2. Create your account

Open the dashboard and follow the on-screen setup wizard. You'll create an admin account and set a workspace name.

3. Connect Jenkins

Navigate to Settings → Connections and click Add Jenkins Instance. You'll need:

# Quick test — verify your token works
curl -u ci-bot:<token> https://jenkins.example.com/api/json

4. Explore the dashboard

After the first sync (usually under 60 seconds), your pipeline data will appear on the Overview tab. From there you can:

• Pin important jobs to your personal dashboard
• Set up failure detection alerts
• Share a read-only link with stakeholders

Next steps

• Pipeline Analytics — deep-dive into build metrics
• Notifications — set up Slack or email alerts
• Environment Variables — fine-tune collector behaviour