Build on check-in
One switch on the hosting page makes every submitted changelist start a build in Build Stream. There is nothing to install and no URL to copy: the platform configures both the Perforce server and Build Stream. The part people miss is the second half, telling Build Stream which depot paths to build.
What the switch does
The Build on check-in card on Server Configuration reads Start a build in Build Stream whenever someone submits. When it is on, the platform installs a change-commit trigger on your live server. Each submit is posted, signed, to your project's Build Stream, the Perforce equivalent of a GitHub push webhook. The trigger only records and forwards; a submit never waits on Build Stream and cannot fail because of it.
The card needs two things to exist: a live Perforce server, and a Build Stream service on the same project.
Turn it on
Open Server Configuration and find the Build on check-in card
The card sits below the connection details. It appears only once the server is live; during creation or a migration it is not shown.
Turn the switch on
The switch moves immediately and the sub-line reads Turning on…. This is the platform recording your request; a background pass then installs the trigger on the live server, usually within a minute. The switch stays clickable throughout, so you can change your mind.
Read the line that appears once it is on
When the live server has caught up, the pending text is replaced by the caveat that matters: Builds start for the depot paths you have mapped to a branch in Build Stream. A submit outside those paths is recorded but does not build.
If it refuses
Turning the switch on can be refused. When it is, the switch shows off and cannot be moved, and the reason is written under the description in a sentence meant to be read as-is.
| Reason shown | What to do |
|---|---|
| this project has no Build Stream service to send check-ins to; create one first | The common one. Add Build Stream to the project; the card offers the link Add Build Stream to this project, which opens the project's settings in the home app. Come back once it is ready. |
| the project's Build Stream service does not have a URL yet; try again once it is ready | Build Stream is still provisioning. Wait a few minutes and try again. |
| build triggers are configured on the primary Perforce server, not the standby | You should not see this. If you do, email [email protected]. |
Turning the switch off is never refused.
Map a depot path to a branch
The switch decides whether submits are sent. Build Stream decides what gets built, and it needs a mapping from your depot to a branch with a build configuration. Until that mapping exists, submits arrive and are recorded, but nothing builds.
| In Build Stream | For Perforce it means | Example |
|---|---|---|
| Repository path | The depot root you build from. | //depot/game |
| Branch name | The stream or top-level directory under that root. | main |
| Together | Submits touching files under this prefix build. | //depot/game/main/... |
| Build configuration | Which platforms build, and whether they build on every commit. | win32-debug, on commit |
The longest matching prefix wins, so //depot/game and //depot/game/tools can be separate repositories. A submit that touches two mapped branches builds both. Files under no mapped prefix are ignored for that submit.
Turned on, but nothing builds
Work through these in order.
Is the switch actually on?
The card must read the mapped-paths caveat, not Turning on… and not a refusal reason. If it is still pending after a few minutes, reload the page.
Is the submitted path mapped?
Compare the changelist's file paths with your mapping. In Build Stream, unmapped submits surface as a notice: Pushes are arriving on branches that are not set up to build, with the depot path and the changelist number. That notice is your confirmation that the trigger is delivering and only the mapping is missing.
Does the project have a Build Stream service, and is it ready?
Both refusal reasons above apply here. Check the project's services in the home app.
Still nothing?
Email [email protected] with the project name and a changelist number that did not build.
What the build machine does
When a submit builds, a build machine syncs your depot with a read-only account the platform created on your server, pinned to the exact changelist that was submitted rather than to the head of the depot, so a build labelled with a changelist contains exactly that changelist. It also checks the server certificate against the fingerprint on your connection card before syncing. Workspaces on the build machines are reused, so the second build of a branch is an incremental sync rather than a full one.
MAJOR STEP START: clone_repo RUN PROCESS START: p4_trust p4 -p ssl:p4.starfall.northwind.example.com:1666 -u dsl_build trust -i AB:12:6D:4F:90:C3:E8:71:2A:55:BD:04:7E:39:F1:C8:6B:2D:A0:14 RUN PROCESS START: p4_sync p4 -p ssl:p4.starfall.northwind.example.com:1666 -u dsl_build -c <workspace> sync //<workspace>/...@<changelist>
Turn it off
Turn the switch off. The sub-line reads Turning off… until the trigger has been removed from the live server. Turning off is never refused, and submits made while it is off are simply not sent.
Where the switch lives and how the check-in reaches Build Stream is also summarised on the overview.
Something out of date or unclear? Email [email protected].