Connecting an Azure DevOps Repo

Orbit deploys from Azure Repos, the git hosting inside Azure DevOps. Connect once, pick a repository, and every push builds and goes live. This guide covers both ways to connect, selecting a repository, and the two things Azure does differently from the other providers.

Two Ways To Connect, And Why There Are Two

Azure DevOps organisations can block third-party applications at the tenant level, and many companies do. If yours does, the sign-in button cannot work for you no matter what we do, so Orbit offers a second door that always works.

Sign in with Microsoft. One click, nothing to copy and paste. Available when your organisation permits third-party applications.
Personal access token. Works for every organisation, including ones that block applications. You paste an organisation name and a token you create in Azure DevOps.

Both doors reach exactly the same features. Neither is a reduced version of the other.

Before You Start

Orbit sees only what your Azure DevOps account sees. You need enough permission on the repository for a service hook subscription to be created, because that subscription is how a push reaches us. Without it the connection succeeds and nothing ever deploys.

Option A: Sign In With Microsoft

In KPanel, click Orbit in the left sidebar.
Click New project.
Leave the mode set to Import Git Repo.
Choose the Azure DevOps tab, then click Connect Azure DevOps.

You are sent to Microsoft to sign in and approve access. Approve it and you are returned to KPanel with your repositories loaded.

If your organisation blocks the application, Microsoft refuses and KPanel shows the reason it gave. That is not something you can retry your way out of: use the personal access token below, or ask an administrator to permit the application.

Option B: Personal Access Token

Create the token in Azure DevOps first.

In Azure DevOps, open User settings, then Personal access tokens, then New Token.
Choose the organisation you want to deploy from.
Grant these three scopes and no more than these three:
- Code (Read) so Orbit can list your repositories and download the commit it is building.
- Code (Status) so the build result appears on the commit and on the pull request.
- Service Hooks (Read and write) so Orbit can subscribe to your pushes.
Copy the token. Azure shows it once.

Then in KPanel:

Open Orbit, then New project, then the Azure DevOps tab.
Under Connect with a personal access token, enter your organisation name. That is the part of your repository address immediately after dev.azure.com, so for https://dev.azure.com/contoso/web-platform/_git/storefront the organisation is contoso.
Paste the token and click Connect Azure DevOps.

Orbit uses the token immediately to list your repositories. If it is refused, you are told which scopes are missing rather than being asked to check your token, because a token that lists repositories but cannot create a service hook is the shape that connects cleanly and then never deploys anything.

Your token is encrypted before it is stored and is only ever used against the organisation you named.

Selecting a Repository

Your repositories appear as a list, named organisation / project / repository. Azure repositories carry three parts, not two, because two projects in one organisation can each hold a repository with the same name.

Click Select next to the one you want, then finish the project as usual: name, framework, build settings, environment variables.

If a Repository Is Missing

Check the organisation. A personal access token belongs to ONE organisation, so a repository in a different one will not appear. Connect that organisation as well.
Check your access on the repository itself in Azure DevOps.
Check whether the repository is disabled in Azure. Orbit does not list disabled repositories, because they cannot be built.

Two Things Azure Does Differently

These are real differences, not gaps we have not got to, and both are stated here rather than discovered later.

Monorepo Root Directory Does Not Skip Pushes

On the other providers Orbit reads the list of files each push changed, and a monorepo project can skip a build when nothing under its Root Directory moved. Azure does not send that list. Orbit therefore builds on every push rather than guessing, because guessing the other way would silently skip deployments you were expecting.

Your Root Directory setting still decides where the build runs. It just does not additionally filter which pushes build.

Pull Requests From Forks Are Not Built

Orbit builds a pull request preview with your project's Preview environment variables. That is safe for a pull request from your own repository and it is not safe for one from a fork, which is a proposal from someone with no relationship to your account.

On GitHub, Orbit can offer a fork preview because GitHub publishes the proposed commit inside your own repository, so we never have to authenticate against the contributor's copy. Azure does not publish an equivalent, so Orbit refuses fork pull requests and says so on the commit rather than leaving a preview that never appears.

Pull requests from branches inside your own repository build normally.

What Happens Next

Push to your production branch and Orbit builds and deploys. The build result is posted back onto the commit in Azure DevOps, so it shows on the commit and on any pull request the commit belongs to, and your branch policies can require it.