ButterStack Quick Setup Guide
Get your first automated build running in 15 minutes
Table of contents
- Before You Begin
- Step 1: Create Your Account
- Step 2: Create Your Project
- Step 3: Choose Task Management
- Step 4: Connect Source Control
- Step 5: Connect Your Build System
- Step 6: Verify the Connection
- Step 7: Wire the Webhook
- Step 8: Test Your Setup
- Step 9: Add Team Notifications (Optional)
- What’s Next?
- Troubleshooting
Before You Begin
The 15 minutes assumes your credentials are already in hand. Gather these first, because hunting for a Jenkins API token mid-setup is what turns 15 minutes into an hour.
| You’ll need | Where to get it |
|---|---|
| A payment card | ButterStack collects a card at signup, before your trial starts. You are not charged during the trial. |
| Source control details | Perforce server address (host:1666), username, and password. Or a GitHub owner/repo plus a personal access token. |
| Jenkins URL, username, API token | Jenkins → your user → Configure → API Token → Add new Token |
| Your Jenkins job name | The exact job ButterStack should trigger. Builds will not fire without it. |
| Admin access to source control | You need to be able to add a webhook in Perforce or GitHub. |
The wizard is the path
ButterStack walks you through Steps 2 through 5 below as a four-step onboarding wizard that starts automatically after signup. This guide follows that wizard screen by screen. You can leave and resume it at any time from/onboarding.Want to look before you wire anything up?
The live demo is a populated ButterStack instance with real builds and asset lineage in it. No credentials, no setup. Worth two minutes before you go gather API tokens.Step 1: Create Your Account
~2 minutes
- Go to butterstack.com/users/sign_up
- Fill in your company name, your name, email, and password, then accept the terms
- Choose a plan
- Enter your card details on the Stripe checkout screen
Your trial starts once the card step completes, and ButterStack drops you straight into the onboarding wizard.
You will also get a confirmation email. Clicking it is not required to finish this guide, so keep going and confirm later.
Which plan should I pick?
Indie covers everything in this guide: Perforce, Lore, Jenkins, Jira, Steam, Unreal, Unity, and Discord. Slack, GitHub, GitLab, Linear, and Trello need Team or above. If you specifically want Slack notifications, see Step 9.Step 2: Create Your Project
Wizard step 1 of 4. ~1 minute
- Project Name - anything, for example
My Awesome Game - Project Type - Game or Web
- Game Engine - Unreal, Unity, or Custom (shown for Game projects only)
- Description - optional
- Click Create Project & Continue
Step 3: Choose Task Management
Wizard step 2 of 4. ~1 minute
Pick where your work items live:
| Option | What happens |
|---|---|
| Use ButterStack Tasks (recommended) | Nothing to configure. Continue immediately. |
| Connect Existing System → Jira | ButterStack sends you into the Jira integration form to collect your Jira URL, email, and API token, then returns you here. |
Trello, Monday.com, and Asana appear in this list but are marked Coming soon and cannot be selected yet.
Fastest path
Choose ButterStack Tasks for your first run. You can connect Jira later from Project → Integrations without redoing anything.Step 4: Connect Source Control
Wizard step 3 of 4. ~3 minutes
Choose one:
Perforce Helix Core (recommended)
| Field | Example |
|---|---|
| Server | perforce.company.com:1666 |
| Username | your.username |
| Password | your Perforce password |
| Workspace / Client | optional, leave empty to use the default |
| Depot Path | optional, the depot name to monitor |
GitHub
Provide your repository details and a personal access token. Requires Team or above.
Lore
Epic’s open source version control. Available on every plan.
Skip for now
You can add source control later, but the test commit in Step 8 will not do anything until you do.
Step 5: Connect Your Build System
Wizard step 4 of 4. ~3 minutes
Jenkins (recommended)
| Field | Example |
|---|---|
| Jenkins URL | https://jenkins.company.com |
| Username | your.username |
| API Token | Jenkins → your user → Configure → API Token |
GitHub Actions
| Field | Example |
|---|---|
| Owner / Organization | your-username or org-name |
| Repository Name | repository-name |
| Personal Access Token | needs the repo and workflow scopes |
GitLab CI is listed but marked Coming Soon. Skip for now is also an option.
Under Automation Preferences, leave the defaults on unless you have a reason not to: deploy successful builds, run tests before deployment, notify on build failures.
Finish the wizard and you land on your dashboard.
Set your Jenkins job name before you test
Go to Project → Integrations → Jenkins and set Job Name to the exact name of the job ButterStack should trigger. Without it, commits are received but no build starts and the integration reports "No Jenkins job name configured." You can also target a specific job per commit with#ci:JobName.Step 6: Verify the Connection
~1 minute
- Go to Project → Integrations
- Open the integration you just created
- Click Test Connection
The Connection Status panel turns green when ButterStack can reach the server. Fix a red result here before moving on, because Step 8 depends on it.
Note on ordering
Test Connection lives on the integration page after the integration is saved, not on the creation form. Create first, then test.Step 7: Wire the Webhook
~3 minutes. This is the step people miss.
ButterStack does not poll your repository. It waits for your source control server to tell it that a commit landed, so the webhook has to exist or nothing in Step 8 will fire.
- Go to Project → Integrations and open your source control integration
- Copy the Webhook URL shown on that page
- Register it with your provider:
- Perforce: add it as a change-commit trigger
- GitHub: Settings → Webhooks → Add webhook, content type
application/json
Full provider-side steps are in the Perforce integration guide and the GitHub integration guide.
Step 8: Test Your Setup
~2 minutes
Make a commit whose message carries a build trigger tag:
git commit -m "Test ButterStack integration #ci"
git push origin main
Recognized trigger tags are #ci, #build, #jenkins, and [ci]. See Build Configuration for the full set.
Triggering is opt-in, so a commit without a trigger tag will not build. Note that the Skip CI Tags setting is not currently consulted at trigger time, so leaving the trigger tag off is the dependable way to skip a build.
Then watch:
- ButterStack receives the webhook and records the commit
- It triggers your Jenkins job or GitHub Actions workflow
- Build status updates on your project dashboard
- Configured notifications fire when the build finishes
That's it
A commit is now flowing through source control into a build, with status coming back into ButterStack. Everything after this is optional.Step 9: Add Team Notifications (Optional)
Discord
Available on every plan, including Indie.
- In Discord: Server Settings → Integrations → Webhooks → New Webhook, then copy the URL
- In ButterStack: Project → Integrations → Discord
- Paste the webhook URL. You can set separate webhooks for builds, assets, alerts, and approvals
Slack
Requires Team or above. On Indie it appears in the integrations list under Needs upgrade.
- In Slack: create an Incoming Webhook for the channel you want
- In ButterStack: Project → Integrations → Slack
- Paste the Incoming Webhook URL
What’s Next?
| Next Step | Description |
|---|---|
| 📊 Understand asset lineage | How a commit becomes a tracked, approved, built asset |
| 🔄 Add More Integrations | Jira, Steam, Unreal, Unity, and more |
| 👥 Invite Your Team | Add team members from Project Settings → Team |
Troubleshooting
Build not triggering?
- Check the webhook actually fired. Look at recent deliveries in your Git provider, or the trigger log on your Perforce server. No delivery means Step 7 is incomplete.
- Check the Jenkins job name is set on the integration. This is the most common cause.
- Check your commit message contains a trigger tag (
#ci,#build,#jenkins,[ci]). - Check the commit landed on the branch you’re monitoring (the Branch field on the integration).
- Check the Jenkins job is not disabled or paused.
Connection failed?
- Re-run Test Connection on the integration page to get the current error.
- Verify the API token has the right permissions. Jenkins tokens are per-user and inherit that user’s job permissions.
- Test from outside your network:
curl -u username:token https://jenkins.yourdomain.com/api/json
- Check your firewall. If your Jenkins or Perforce server is not publicly reachable, ButterStack cannot reach it either. Contact support for static IP ranges to allowlist.
Integration not in the list?
It is probably plan gated. Integrations you cannot add on your current plan appear under Needs upgrade on the integrations page. Perforce, Lore, Jenkins, Jira, Steam, Unreal, Unity, and Discord are available on every plan.