Build Stream on Dev Stream Labs
Build Stream turns commits into builds. You connect a repository, tell it which branches to build and for which platforms, and every push to those branches becomes a build you can watch, read the log of, and download. This guide covers the whole path from adding the service to a project through to a downloadable artifact. Every name, host and address you see here is example data for a fictional studio called northwind and its project starfall.
What you get
One Build Stream service per project. When it is ready you have a build farm that already knows your project's toolchain, a connections page where one repository is linked, a branch table that decides what builds and when, and a Builds page where each commit turns into one build per configuration. Artifacts are downloadable from the app, and deleted builds sit in a recoverable trash for a while before they are gone.
| What it is | Where you find it | |
|---|---|---|
| Connection | The one repository the project builds from, with its credentials and webhook. | Build Stream → Source Control Connections |
| Branch table | Which branches build, on what schedule, at what version, and for which build configurations. | Branch Configuration on the repository card |
| Builds | One group per commit, one job per build configuration, each with a log and a download. | Build Stream → Builds |
| Commits | Every push the webhook delivered, with its files, contributors and related builds. | Build Stream → Commits |
| Deleted builds | A holding area for builds you deleted, restorable until they are permanently removed. Retention is currently 24 hours. | Build Stream → Deleted Builds |
| Signing and notifications | Per-branch platform signing for Android, iOS and macOS, and a Slack or Discord webhook for results. | The repository card, under Build notifications and each branch's platform configuration |
Choose your provider
A project holds one repository today, so the first decision is which provider and which method. The five self-service paths below lead to the same branch table and the same Builds page; they differ in what you hand over and who creates the webhook.
| GitHub App | GitHub (token) | Bitbucket Cloud | Diversion (beta) | |
|---|---|---|---|---|
| You provide | An App install, then you pick a repository. | Username, repository and a Personal Access Token. | Workspace and an API token. | Server URL, API token and the repository name. |
| Repositories you can pick | Any the App can see. | One you name. | Listed after Load repositories. | One you name. |
| Webhook | Created for you. | You create it, from Manage Webhook. | You create it, from Manage Webhook. | You create it. |
| Delivery is verified | No signature check today. Deliveries are matched to your App installation and repository. | No signature check today. | No signature check today. | No signature check today. |
| Branch list in the app | Yes. | Yes. | Yes. | No. You type the name. |
| Pushes to a branch you have not added | Recorded as a notice. | Recorded as a notice. | Acknowledged and dropped. Nothing is shown in the app. | Rejected, not recorded. |
| Version from releases | Yes. | No. | No. | No. |
If the form has a Personal Access Token field, you also create the webhook. The GitHub App path has neither.
How a build happens
Everything in this guide sits somewhere on this chain. When a build does not appear, the chain is also the order to check things in.
| Stage | What happens | Where you see it |
|---|---|---|
| Push | Someone pushes to main on your provider. | Your provider. |
| Webhook | The provider posts the push to your project's Build Stream webhook URL. The GitHub App does this through the App; every other path uses a webhook you created. | Your provider's webhook delivery log; the Manage Webhook: block on the repository card holds the URL. |
| Commit recorded | Build Stream records the push as a commit. If the branch is not in the branch table, the push is recorded as a notice instead of a build. | Commits, and the notice on the connections page. |
| Autobuild configurations | The branch's schedule and build configurations decide whether to build now, nightly or weekly, and one job is created per configuration. | Branch Configuration |
| Build machine | A machine on the farm that has your toolchain takes the job, syncs the exact commit that was pushed rather than the head of the branch, and runs the build. | Builds, then View Log |
| Artifact | The finished build is uploaded and the job ends as Build succeeded or Build failed. A green job on a branch becomes its Last Known Good. | Download on the job row |
Words this guide uses
| Term | Meaning |
|---|---|
| Repository, connection | The one repository a project builds from, shown as a card on Source Control Connections titled northwind-games/starfall. The guide says "connection" for the card and "repository" for the thing on your provider. |
| Branch | A row in the branch table. Only branches in the table build; a push anywhere else is recorded but not built. |
| Build configuration | A platform and variant your toolchain can produce, named like win32-release. A branch can have several; each push creates one job per configuration. |
| Build schedule | When a branch builds: On Every Commit, Nightly Only or Weekly Only. Nightly and weekly build the latest commit at the time you choose. |
| Last Known Good | The most recent successful build of a branch, badged Last Known Good on the Builds page. It moves forward with each green build. |
| Artifact | The file a successful job produced, behind the Download button. One per job. |
| Unconfigured branch | A branch that received a push but is not in the branch table. The connections page shows Pushes are arriving on branches that are not set up to build until you add it. |
Where things live in the app
Build Stream is added to a project as a service. Once it is ready, a Build Stream section appears in the project sidebar with four pages: Builds, Commits, Source Control Connections and Deleted Builds. On narrow screens the same pages are labelled Build Stream, Commits, Connections and Deleted Builds.
Projects with a hosted Perforce server also have a Source Control Hosting section with Server Configuration and Backup & Export. Those pages are covered by the Perforce guide.
If your project does not have Build Stream yet, the next page, Add Build Stream to your project, walks through both ways to add it.
The pages in this guide
- Build Stream on Dev Stream Labs This page: what the service is and how the pieces fit.
- Add Build Stream to your project Add Build Stream when you create a project or to a project you already have, and what happens until it is ready.
- Connect a GitHub repository The GitHub App path and the token path, the webhook, and how to disconnect.
- Connect a Bitbucket Cloud repository The API token, the repository picker, and the webhook you create in Bitbucket.
- Connect a Diversion repository The form, the webhook, and why the branch has to exist in Build Stream before the first push.
- Connect your hosted Perforce server The Hosted Perforce server form, the depot path, how streams map to branches, and the Check-in delivery status.
- Branches and build configurations Add a branch, set its version and schedule, pick build configurations, and read the warnings.
- Your first build Push, watch the Builds page, read the log, download the artifact, and cancel or delete builds.
- Signing and notifications Android, iOS and macOS signing per branch, and Slack or Discord notifications.
- Troubleshooting and FAQ Connection and webhook problems, the build failure messages, farm warnings, and where to get help.
Something out of date or unclear? Email [email protected].