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 either its webhook or its scheduled check. | 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. The Build Now button lives here too. | Build Stream → Builds |
| Commits | Every push that was delivered or found by a scheduled check, 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, Windows signing profiles for the project, and a Slack or Discord webhook for results. | The repository card, under Build notifications and each branch's platform configuration; Windows profiles under Build Stream → Code Signing |
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, how Build Stream learns about a commit, and whether a delivery can be checked for authenticity before it is trusted.
The table is what the service does for each path today. Two rows decide how much you can trust what you see on the Commits page and what happens to a push on a branch you never added: Delivery is verified and Pushes to a branch you have not added.
| GitHub App | GitHub (token) | Bitbucket Cloud | Diversion (beta) | Hosted Perforce | |
|---|---|---|---|---|---|
| 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. | A depot path on the server you already host with us. |
| Repositories you can pick | Any the App can see. | One you name. | Listed after Load repositories. | One you name. | One depot path you type. |
| How commits arrive | Webhook, a scheduled check, or both. The webhook is created for you. | Webhook, a scheduled check, or both. You create the webhook from Manage Webhook. | Webhook, a scheduled check, or both. You create the webhook from Manage Webhook. | Webhook. You create it. | Every submit, once Build on check-in is on. Nothing to create. |
| Delivery is verified | Yes. Each delivery is signature-checked; a bad signature is refused. | No. Deliveries to a token connection are accepted unsigned and recorded as unverified. | No signature check. | No signature check. | Yes. Every submit is signed by the platform. |
| Branch list in the app | Yes. | Yes. | Yes. | No. You type the name. | No. You type the stream or directory. |
| 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. | Recorded as a notice. |
| Version from releases | Yes. | No. | No. | No. | No. |
If the form has a Personal Access Token field, you also create the webhook, and its deliveries are not signature-checked. The GitHub App path has neither a token nor a webhook to create, and every delivery is checked.
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. |
| Delivery | The provider posts the push to your project's Build Stream webhook URL, or, for a GitHub token or Bitbucket connection set to check on a schedule, the service asks the provider a few minutes later whether the branch head moved. The GitHub App and hosted Perforce deliver through hooks registered for you; every other webhook is one you created. | Your provider's webhook delivery log; the Manage Webhook: block on the repository card holds the URL. A polled branch shows when it was last checked under its row. |
| Commit recorded | Build Stream records the push as a commit. If the branch is not in the branch table, a GitHub or hosted Perforce push is recorded as a notice instead of a build; a Bitbucket or Diversion push to an unknown branch is dropped and leaves no trace in the app. | Commits, and the notice on the connections page. |
| Autobuild configurations | The branch's schedule decides whether to build now (On Every Commit), wait for the time you set (Nightly Only, Weekly Only) or do nothing until someone presses Build Now (On Demand (Build Now only)). When a build is due, one job is created per build 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. |
| Connection method | How the service learns about a commit. The GitHub token and Bitbucket forms ask How should we learn about new commits? and offer Tell us instantly (webhook), Check for changes on a schedule or Both. The guide says "webhook" for the first and "scheduled check" for the second. The GitHub App, Diversion and hosted Perforce always use a hook. |
| Branch | A row in the branch table. Only branches in the table build; a push anywhere else is at best recorded as a notice, never built. |
| Build configuration | A platform and variant your toolchain can produce, named like win32-release. A branch can have several; each build creates one job per configuration. |
| Build schedule | When a branch builds on its own: On Every Commit, Nightly Only, Weekly Only or On Demand (Build Now only). Nightly and weekly build the latest commit at the time you choose; on demand never builds until someone asks. |
| Build Now | The button on the Builds page that builds a branch's latest commit on request, on any schedule, even if that commit was built before. |
| 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. For GitHub and hosted Perforce connections the connections page shows Pushes are arriving on branches that are not set up to build until you add it. Bitbucket and Diversion pushes to such a branch are dropped without a notice. |
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 five pages: Builds, Commits, Source Control Connections, Code Signing and Deleted Builds. Code Signing holds the project's Windows signing profiles and is listed for administrators only. On narrow screens the same pages are labelled Build Stream, Commits, Connections, Code Signing 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 or the scheduled check, and how to disconnect.
- Connect a Bitbucket Cloud repository The API token, the repository picker, and the webhook you create in Bitbucket or the scheduled check instead.
- 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 or press Build Now, 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, Windows signing profiles, and Slack or Discord notifications.
- Ship iOS to TestFlight with no Mac
- Troubleshooting and FAQ Connection and webhook problems, the build failure messages, farm warnings, and where to get help.
- Build actions Run your own Python or JavaScript scripts at fixed points in every build: the hooks, what a script is told, secrets, failures and limits. Six pages at the end of this guide.
Something out of date or unclear? Email support@devstreamlabs.com.