Build Configuration

Control when builds are triggered, how they are tracked, and when they need approval

Table of contents

1. How ButterStack Thinks About Builds
2. The Three-Step Build Model
3. Build Triggers
   1. Commit message tags
   2. Skip tags
   3. Customizing trigger tags
4. Jenkins Job Configuration
5. Commit Processing Settings
   1. Approval Tags
   2. Skip CI Tags
   3. Task Linking Patterns
6. Approval Triggers
   1. Trigger modes
   2. Content-based rules
7. Working With a Build Run
8. Agentic Build-Failure Investigation
9. AI Analysis Settings
10. Testing Your Configuration
11. Troubleshooting
    1. A tagged commit produced no build
    2. The build passed in Jenkins but is not green in ButterStack
    3. Approvals are being requested for everything
    4. Status is stale
12. Next Steps

How ButterStack Thinks About Builds

That distinction shapes everything on this page. There is no ButterStack build script, no runner pool, no YAML pipeline definition, and no build cache to configure. Those all live in your existing CI system, and you configure them there exactly as you do today.

What you configure in ButterStack is the layer around the build:

The Three-Step Build Model

Every build run in ButterStack is tracked as three steps:

Each step carries its own status: pending, in_progress, success, failed, cancelled, or skipped. The build run then rolls those up into an overall status of pending, in_progress, success, failed, cancelled, or mixed.

mixed is the interesting one. It means the steps disagree, for example the external build succeeded but approval was rejected. A green Jenkins job is not automatically a green build run.

The build run itself also has a lifecycle status: queued, preparing, building, completed, failed, cancelled, or passed_pending_approval.

Build Triggers

Commit message tags

ButterStack triggers a build when a commit message contains one of your trigger tags. This is the primary mechanism, and it is deliberately opt-in so that not every commit burns a build.

git commit -m "Fix character shader #ci"

#ci works everywhere. If you only remember one tag, remember that one.

Perforce changelist descriptions and Git commit monitoring accept a wider set, matched case-insensitively anywhere in the message:

To target a specific Jenkins job from a single commit, without changing your integration settings:

git commit -m "Rebuild lighting #ci:NightlyLightmaps"

Skip tags

Defaults are #skip-ci, [skip ci], and #skipci. Configure them now if you want them in place for when the behavior lands, but do not rely on them today.

Customizing trigger tags

Trigger tags are set per integration, under Project → Integrations → your source control integration:

Skip tags are set per project, under Project → Settings (see Commit Processing Settings below).

Jenkins Job Configuration

Under Project → Integrations → Jenkins:

Commit Processing Settings

Under Project → Settings, the Commit Processing Settings section controls how ButterStack reads your commit messages.

Approval Tags

Comma-separated tags that flag a commit as needing approval.

Default: #approval, #approve, #review, #approvals

Skip CI Tags

Comma-separated tags intended to suppress a build. Not currently consulted by any trigger path - see Skip tags above. Your value is saved, but has no effect today.

Default: #skip-ci, [skip ci], #skipci

Task Linking Patterns

Comma-separated regular expressions that link a commit to a task. This is what connects a build back to the work item it came from.

Default patterns and what they match:

Approval Triggers

Under Project → Settings, the Approval Triggers section decides when a commit needs human sign-off before its build run can go green.

Trigger modes

Content-based rules

Approval can also be required based on what a commit touches, which is usually how art and audio pipelines want it:

A build run whose approval step is outstanding sits at passed_pending_approval rather than completed, even when Jenkins reported success.

Working With a Build Run

Open a build run from Project → Builds. From there you can:

Agentic Build-Failure Investigation

For a failed build run, ButterStack can run an AI investigation that reads the build context and reports a likely cause.

Requirements:

• The Team plan or higher
• Available credits, and the account’s daily investigation limit not yet reached
• The build run must have actually failed. The action is unavailable on passing builds.
• Agentic investigation must be enabled on both the account and the project

Investigations consume credits. The cost is reserved against your balance when the investigation starts, and you will be told up front if your balance is insufficient.

AI Analysis Settings

Under Project → Settings, the AI Analysis Settings section lets a single project override the account-level AI configuration:

• Provider and Model, left blank to inherit the account default
• Anthropic API Key or OpenAI API Key, to run analysis against your own account

Leave all of this alone unless you have a specific reason to pin a model or bill AI usage to your own provider account.

Testing Your Configuration

1. Confirm the integration is healthy. Open the integration and click Test Connection. Fix a red result before anything else.
2. Confirm the webhook is registered. ButterStack does not poll. Check recent deliveries in your Git provider, or your Perforce trigger log.
3. Commit with a trigger tag. Use #ci and watch Project → Builds for a new run.
4. Check the three steps individually. A mixed overall status means one step disagrees with the others, most often an outstanding or rejected approval.

Troubleshooting

A tagged commit produced no build

1. Job Name is not set on the Jenkins integration. Most common cause by a wide margin.
2. The webhook never fired. No delivery in your provider’s log means ButterStack never heard about the commit.
3. The commit was on a branch you are not monitoring. Check the Branch field on the integration.
4. The tag does not match. Compare the commit message against the recognized tag set. Note that a skip tag is not a cause here, since skip tags are not currently consulted.

The build passed in Jenkins but is not green in ButterStack

Check the approval step. A run sitting at passed_pending_approval is waiting on a human, and a run at mixed has at least one step that did not succeed.

Approvals are being requested for everything

Check Always require approval for all commits in Approval Triggers, then check whether your File Extensions and Paths Requiring Approval rules are broader than you intended. Add generated or vendored directories to Paths to Exclude from Approval.

Status is stale

Click Refresh on the build run to re-pull from Jenkins. If it happens repeatedly, a webhook is being dropped rather than a status being mis-read.

Next Steps

1. Set Up Steam Deployment - Track releases to Steam
2. Configure Discord Notifications - Get build alerts
3. Unreal Build Setup - Engine-specific build guidance
4. Add More Integrations - Connect additional tools

Need Help? Contact support@butterstack.com or join our Discord community.