Connecting Jenkins

BuildButler uses the Jenkins REST API to collect build data. This guide walks through creating credentials and adding your first connection.

Generate a Jenkins API token

1. Log in to Jenkins as the user you want BuildButler to use (a service account is recommended).
2. Click your username in the top-right → Configure.
3. Under API Token, click Add new Token.
4. Give it a name like buildbutler and click Generate.
5. Copy the token — you won't be able to see it again.

Add the connection in BuildButler

Navigate to Settings → Connections → Add Jenkins Instance and fill in the form:

{
  "name": "Production Jenkins",
  "url": "https://jenkins.example.com",
  "username": "ci-bot",
  "token": "11a2b3c4d5e6f..."
}

Click Test Connection to verify. BuildButler will call /api/json?tree=jobs[name] and confirm it can read your job list.

Permissions required

The API user needs at minimum:

• Overall/Read — access the API
• Job/Read — list and read job configs
• Run/Read — access build details and logs

If you use the Role-Based Authorization Strategy plugin, create a role with these permissions and assign it to your service account.

Multiple instances

You can connect as many Jenkins controllers as you like. Each connection syncs independently and appears as a separate source in the dashboard filter bar.

# List all connections via the CLI
buildbutler connections list
 
# Output
# ┌────┬───────────────────┬──────────────────────────────────┬────────┐
# │ ID │ Name              │ URL                              │ Status │
# ├────┼───────────────────┼──────────────────────────────────┼────────┤
# │ 1  │ Production        │ https://jenkins.example.com      │ Active │
# │ 2  │ Staging           │ https://jenkins-stg.example.com  │ Active │
# └────┴───────────────────┴──────────────────────────────────┴────────┘

Troubleshooting