Connect a Diversion repository

Fill in the form

1. Open Connections and choose Diversion

   In the project sidebar open Build Stream and then the Connections page. Click Add and choose Diversion. A card expands with three fields and an empty Branch Configuration: table.

2. Fill in the three fields

   The Diversion connection form

   Field	What to enter	Example
   Server URL	The Diversion service you use. The field is pre-filled with the hosted service; change it only if you use a different endpoint.	https://diversion.com
   API Token	A Diversion API token with read access to the repository. It is masked as you type and stays masked on the card.	dv.token.…
   Repo	The repository name exactly as Diversion shows it.	starfall

   Create stays disabled until all three have a value. Nothing is checked against Diversion at this point: a wrong token or repository name is accepted and only shows up when the first build tries to fetch the code.

   

3. Create the connection

   Click Create. The toast Source Control Added confirms it and the form becomes a card. The card title pairs your organization's URL name with the repository, for example northwind/starfall; that first part is not a Diversion workspace, it is the organization the project belongs to.

To change the server, token or repository later, open the card with Config. The same three fields appear under Configuration: with a Save Changes button that enables once something differs from what is saved. The token field shows dots when a token is stored; leave it alone to keep the existing one.

Create the webhook

The card's Manage Webhook: block shows the Webhook URL with a Copy button and a masked Secret. Unlike the GitHub and Bitbucket URLs, the Diversion URL carries the organization and project in its path; that is how a delivery finds your project:

https://buildstream.starfall.northwind.example.com/api/build-stream/webhooks/dv/northwind/starfall/

Build Stream does not create the webhook in Diversion for you. In Diversion, add a webhook on the repository that posts to this URL and subscribes to the commit-created event. Build Stream acts on exactly one event type, v1.repo.commit.created; any other type is answered with ignored and does nothing. The Secret on the card is not checked on incoming Diversion deliveries today, so you do not need to configure it on the Diversion side; keep the webhook URL private instead.

For every accepted commit Build Stream records the author, the commit id and message, and marks the push for the scheduler, which then applies the branch's schedule and build configurations. The commit appears on the Commits page within a few seconds of the delivery.

Add the branch first

A Diversion delivery is matched in three steps: the organization in the URL, the project in the URL, and then the branch name in the payload against the branches in your Branch Configuration table. If the branch is not there, the delivery is rejected with a 400 and the message Could not find Source Control Server for main (with the branch name in place of main). Nothing is recorded: no commit, no build, and no notice in the app. Diversion shows the failed delivery in its own log, and Build Stream will not pick that commit up later.

Because the app cannot list Diversion branches, you type the name into the row's branch-name field. It must match the branch name Diversion sends exactly, including case. Adding rows is covered on Add a branch.

A delivery can also fail before the branch check. A 400 naming your organization or project means the URL in Diversion does not match the one on the card: copy it again from Webhook URL. Malformed webhook payload means the body was not what Diversion normally sends; email [email protected] with the delivery if you see it.

What Diversion connections do today

Once a commit has been accepted, continue with Your first build. For a commit that Diversion delivered but Build Stream rejected, start at Troubleshooting: webhooks.