Connect a GitHub repository

Which method

Use the GitHub App unless you cannot. It is the path that needs no credential from you and no webhook step, and the platform can see every repository the App was granted. Use the token path when the App cannot be installed on the account that owns the repository, for example an organization whose admins do not allow third-party Apps, or when nobody on your team administers the repository at all and the scheduled check is the only way in.

Both paths start on Build Stream → Source Control Connections. The page is headed Connections, with a counter such as 0 / 1 repositories, the line Manage source control repositories for your project, and an Add button. The counter is the one-repository rule: a project holds one repository today, and once it has one the page adds Maximum of 1 repository allowed and disables Add.

Add opens a menu with GitHub, Diversion, Bitbucket and Perforce. Choose GitHub. A card headed Add New Source Control expands with the line Fill in the configuration below to create a new source control server and repository. The GitHub App section is at the top of the card and the token form is below it, separated by OR CONNECT MANUALLY.

Connect with the GitHub App

The section is headed Connect with GitHub App and reads Install the Dev Stream Labs GitHub App to connect repositories without a personal access token. Under it, one button: Use Already-Installed App. The hint beside it explains the order of operations: start with that button, which connects a repository from an account where the App is already installed, and if it turns out the App is not installed yet you are offered the option to configure it.

1. Press Use Already-Installed App

   The button shows Starting... and sends you to GitHub to authorize. GitHub asks you to confirm your identity so the platform can see which of your accounts have the App installed. Nothing is written to your repositories at this step.

2. You come back to Connections in one of three states

   GitHub returns you to the connections page and the App section shows a coloured line. Which line tells you what happened.

   The three states the GitHub App section can return in

   Line you see	What it means	Next
   Choose the GitHub repository to connect.	The App is installed somewhere you can reach and the repositories it can see have been loaded.	Continue to the next step.
   This environment's GitHub App is not installed on any account you can access. Use Configure GitHub App below to install it.	The App is not installed on any account you belong to.	Follow If the App is not installed yet.
   GitHub App installation failed.	GitHub sent you back with an error, or the round trip did not complete.	Read the message beside it; the common causes are in Troubleshooting. Try again from the button.

   

   

3. Pick the repository

   The picker's placeholder is Select repository; it lists repositories as owner/name, for example northwind-games/starfall, and has a search box. If the App can see exactly one repository it is preselected. If the list is empty the section tells you This installation has no repository access. In GitHub, open the app's installation settings and grant it access to at least one repository, then start over. and offers a Start over link.

4. Press Connect Selected Repository

   The button reads Connecting... while the repository is imported, then the page reloads on the connections page with the new card. The green line GitHub App installation connected. is the success state of the round trip; the card is the proof the repository is in.

   

The card is titled northwind-games/starfall and carries a GitHub App badge with the line Connected through Dev Stream Labs GitHub App and, under it, Repository access is managed by the GitHub App. No personal access token is required. There is no webhook block on this card: the App delivers pushes to the platform, which checks each delivery's signature against the App's own webhook secret and routes it to your project by installation and repository. A delivery that fails that check is refused.

If the App is not installed yet

When the round trip reports that the App is not installed on any account you can access, a second button appears beside the first: Configure GitHub App. It sends you to GitHub's install page for the App, which is listed in GitHub as DevStreamLabs Git.

1. Press Configure GitHub App

   GitHub asks where to install the App: your personal account or an organization you administer. If your organization requires approval for third-party Apps, GitHub turns this into a request to its owners and you cannot finish until one of them approves.

2. Choose which repositories the App may see

   GitHub offers all repositories or a list you pick. Only the repositories you grant here appear in the picker back on the connections page. Granting one is enough.

3. Finish in GitHub and pick the repository

   GitHub sends you back to the connections page in the Choose the GitHub repository to connect. state. From here the steps are the same as picking the repository above.

Connect with a token

The form under OR CONNECT MANUALLY starts with the connection-method choice, then names one repository and the token the build machines will use to read it. Above the fields a read-only Account URL line assembles https://github.com/, the account and the repository as you type, so you can see the address it will use.

1. Create a token in GitHub

   Build Stream uses the token for three things: it checks the token against GitHub when you save, it lists the repository's branches for the branch table, and the build machine clones the repository with it. That needs read access to the repository's contents and to its metadata, and nothing more. You do not need any permission over webhooks, because you create the webhook yourself. A fine-grained token scoped to the one repository with read access to contents (GitHub adds metadata automatically) is the tightest fit; a classic token needs the repository scope for a private repository. Copy the token when GitHub shows it; it is shown once. For a repository anyone can read, tick Public repository instead and skip the token, as described in the next section.

2. Fill in the four fields

   The fields on the manual GitHub form

   Field	What goes in it
   Account / Organization	The owner of the repository as it appears in the URL, for example northwind-games.
   Username	The GitHub username the token belongs to. For a personal repository this is the same as the account. Hidden when Public repository is ticked.
   Repository	The repository name alone, for example starfall. The placeholder reads my-repo.
   Personal Access Token	The token from the previous step. The field is masked. Hidden when Public repository is ticked.

3. Optionally add branches now, then press Create

   The card lets you add branch rows before the repository exists; they are created with it. You can also leave that for later. Create stays disabled until the account, the repository and, unless the repository is public, the username and token are filled. When you press it the platform checks the token against GitHub before saving anything. A rejected token comes back as The GitHub personal access token was rejected (invalid or expired). Please generate a new token and try again. and nothing is saved. If GitHub is rate limiting or unreachable the save goes through unverified rather than locking you out.

4. Create the webhook in GitHub

   Skip this step if you chose Check for changes on a schedule; the card then has no webhook block. Otherwise the new card shows a Manage Webhook: block with a Webhook URL row and a Copy button, followed by the Webhook secret field described below. Copying confirms with a Copied toast.

   The webhook URL for the example projectCopy

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

   In GitHub, open the repository's settings, go to its webhooks and add one. Paste the URL as the payload URL, set the content type to JSON (the endpoint parses a JSON body and rejects a form-encoded one), paste the secret you generated on the card, and choose to send push events. Push is what starts builds; any other event is acknowledged and ignored. Save the webhook; GitHub sends a ping, which is one of the ignored events, so a green delivery there means the URL is reachable.

   

The card also has a Config button that reopens the fields under Configuration: with a Save Changes button. The stored token is never sent back to the browser: the Personal Access Token row reads •••••••• set with a Replace link. Leave it alone to keep the current token, or press Replace and paste a new one; a replaced token is checked against GitHub the same way. The line Edits to existing branches save automatically. under the fields marks where the explicit save ends and the branch table's autosave begins.

How Build Stream learns about commits

The manual form opens with a box headed How should we learn about new commits? and three options. The choice is made when you connect; it is not a setting on the card afterwards. The GitHub App path does not ask, because the App delivers pushes itself.

Two checkboxes sit under the options. Public repository reads Anyone can read it, so no username or token is needed. Ticking it hides the Username and Personal Access Token fields and connects the repository with no credential at all; that is enough for the scheduled check and for the build machine's clone, but a webhook still needs someone with admin rights on the repository to create it in GitHub. Build the current commit now appears only when the chosen method includes the scheduled check and reads Otherwise the first check only fills in the commit history, and the first build is the next commit or Build Now. Tick it if you want a build of the branch head as soon as the first check runs.

On a repository that is checked on a schedule, the card carries a Checked on a schedule badge. Beside it the card reads New commits are picked up within a few minutes. No webhook or admin access to the repository is needed. for the schedule-only method, or The webhook starts builds; the scheduled check catches any delivery the host dropped. for Both, followed by Each branch below shows when it was last checked. The first check records the commit history without building it; use Build Now for the first build. Every confirmed branch row then shows one of three lines, refreshed every 30 seconds or so while the page is open:

The webhook secret

Under Webhook URL the card shows a Webhook secret field. It is write-only: the API only reports whether a secret is stored, so a stored secret shows as •••••••• set with a Replace link, and there is no way to read it back. The hint under the field reads Stored write-only. Copy a new secret into the repository's webhook settings before saving; the old one stops verifying once saved.

1. Press Generate

   Generate fills the field with a random 48-character value made in your browser. You can also press Replace and type your own.

2. Copy it into GitHub

   Copy beside the field is enabled once the field holds a value and confirms with Copied. Paste it as the secret on the webhook in GitHub's repository settings before you save on the card; the field is visible while you edit it, so this is the moment to copy it.

3. Press Save secret

   Save secret stores it and confirms with the toast Webhook secret saved. The field returns to •••••••• set.

Branches come next

A connected repository builds nothing until it has a branch in the Branch Configuration table. Both GitHub paths list the repository's branches from GitHub, so Add Branch offers a picker rather than a text field. On an App connection the version column can also be filled from the repository's releases; on a token connection you type the version. That table, its schedule and its build configurations are the subject of Branches and build configurations.

Pushes that arrive by webhook before the branch is added are not lost. The connections page shows Pushes are arriving on branches that are not set up to build with the branch and the latest commit, and clears the notice once you add the branch. That behaviour is described in Pushes to a branch you have not added. The scheduled check only looks at branches in the table, so it records nothing for a branch you have not added.

Disconnect or delete

There are two different removals and the card offers both. Read the dialog title before you confirm.

Disconnect GitHub App opens a dialog of the same title that reads This removes the GitHub App connection for this project. It won't uninstall the app from your GitHub account. To fully disconnect, uninstall it from GitHub afterward. Cancel backs out; Disconnect reads Disconnecting... while it runs and finishes with a toast titled GitHub App Disconnected: The GitHub App was disconnected from this project.

Because a project holds one repository, deleting is also how you switch repositories, switch from the token path to the App, or change the connection method: delete, then Add again. If something goes wrong on the way, email support@devstreamlabs.com with the project name and the repository.