Skip to content

[Improve] Simplify Azure DevOps setup #267

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mrubens wants to merge 4 commits into
base: develop
Choose a base branch
from
Open

[Improve] Simplify Azure DevOps setup #267

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
66c7283
Improve Azure DevOps setup flow
mrubens Jul 13, 2026
1694de0
Improve Azure DevOps account linking setup
mrubens Jul 13, 2026
47edd97
Require Azure DevOps account linking
mrubens Jul 13, 2026
71948cc
Clarify Azure DevOps tenant requirement
mrubens Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/gentle-ado-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@roomote/web': patch
---

Guide Azure DevOps setup through organization-first PAT creation, require Microsoft Entra account linking for Azure DevOps Services, automatically reuse existing Microsoft or Teams app credentials, clarify when a tenant ID is required, hide advanced credentials by default, and allow saved optional source-control settings to be cleared.
76 changes: 38 additions & 38 deletions apps/docs/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,43 +229,43 @@ as per-task auth tokens or workspace paths.

### Source control providers

| Env var | Required | Used for |
| ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------ |
| `R_GITHUB_APP_SLUG` | GitHub | GitHub App slug. |
| `R_GITHUB_APP_ID` | GitHub | GitHub App ID. |
| `R_GITHUB_APP_PRIVATE_KEY` | GitHub | Raw GitHub App private key PEM, usually with newlines escaped as `\\n`. |
| `R_GITHUB_CLIENT_ID` | GitHub | GitHub OAuth client ID. |
| `R_GITHUB_CLIENT_SECRET` | GitHub | GitHub OAuth client secret. |
| `R_GITHUB_WEBHOOK_SECRET` | GitHub | GitHub webhook secret. |
| `GITHUB_MCP_SERVER_URL` | Optional | GitHub MCP server URL override. |
| `GITHUB_AUTOMATED_SKIP_REPOS` | Optional | Repository skip list for automated GitHub processing. |
| `GITHUB_AUTOMATED_SKIP_OWNERS` | Optional | Owner skip list for automated GitHub processing. |
| `GITLAB_TOKEN` | GitLab | GitLab personal access token for source-control setup. |
| `GITLAB_BASE_URL` | Optional | GitLab base URL for self-managed GitLab. |
| `GITLAB_CLIENT_ID` | Optional | GitLab OAuth application ID for personal account linking and merge request comment triggers. |
| `GITLAB_CLIENT_SECRET` | Optional | GitLab OAuth application secret for personal account linking and merge request comment triggers. |
| `GITLAB_WEBHOOK_SIGNING_TOKEN` | Optional | GitLab webhook signing token. |
| `GITLAB_WEBHOOK_SECRET` | Optional | GitLab webhook secret. |
| `GITEA_BASE_URL` | Gitea | Gitea base URL. |
| `GITEA_TOKEN` | Gitea | Gitea access token. |
| `GITEA_USERNAME` | Optional | Gitea username. |
| `GITEA_CLIENT_ID` | Optional | Gitea OAuth client ID. |
| `GITEA_CLIENT_SECRET` | Optional | Gitea OAuth client secret. |
| `GITEA_WEBHOOK_SECRET` | Optional | Gitea webhook secret. |
| `BITBUCKET_TOKEN` | Bitbucket | Atlassian API token with Bitbucket scopes. |
| `BITBUCKET_USERNAME` | Bitbucket | Atlassian account email that owns the API token. |
| `BITBUCKET_BASE_URL` | Optional | Bitbucket base URL. Defaults to `https://bitbucket.org` (Cloud only). |
| `BITBUCKET_CLIENT_ID` | Optional | Bitbucket OAuth client ID for personal account linking. |
| `BITBUCKET_CLIENT_SECRET` | Optional | Bitbucket OAuth client secret for personal account linking. |
| `BITBUCKET_WEBHOOK_SECRET` | Optional | Bitbucket webhook secret. |
| `ADO_ORGANIZATION` | Azure DevOps | Azure DevOps organization. |
| `ADO_TOKEN` | Azure DevOps | Azure DevOps access token. |
| `ADO_BASE_URL` | Optional | Azure DevOps base URL. |
| `ADO_USERNAME` | Optional | Azure DevOps username. |
| `ADO_CLIENT_ID` | Optional | Microsoft Entra client ID for Azure DevOps OAuth. |
| `ADO_CLIENT_SECRET` | Optional | Microsoft Entra client secret for Azure DevOps OAuth. |
| `ADO_TENANT_ID` | Optional | Microsoft Entra tenant ID for Azure DevOps OAuth. `R_MICROSOFT_TENANT_ID` is also accepted. |
| `ADO_WEBHOOK_SECRET` | Optional | Azure DevOps webhook secret. |
| Env var | Required | Used for |
| ------------------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `R_GITHUB_APP_SLUG` | GitHub | GitHub App slug. |
| `R_GITHUB_APP_ID` | GitHub | GitHub App ID. |
| `R_GITHUB_APP_PRIVATE_KEY` | GitHub | Raw GitHub App private key PEM, usually with newlines escaped as `\\n`. |
| `R_GITHUB_CLIENT_ID` | GitHub | GitHub OAuth client ID. |
| `R_GITHUB_CLIENT_SECRET` | GitHub | GitHub OAuth client secret. |
| `R_GITHUB_WEBHOOK_SECRET` | GitHub | GitHub webhook secret. |
| `GITHUB_MCP_SERVER_URL` | Optional | GitHub MCP server URL override. |
| `GITHUB_AUTOMATED_SKIP_REPOS` | Optional | Repository skip list for automated GitHub processing. |
| `GITHUB_AUTOMATED_SKIP_OWNERS` | Optional | Owner skip list for automated GitHub processing. |
| `GITLAB_TOKEN` | GitLab | GitLab personal access token for source-control setup. |
| `GITLAB_BASE_URL` | Optional | GitLab base URL for self-managed GitLab. |
| `GITLAB_CLIENT_ID` | Optional | GitLab OAuth application ID for personal account linking and merge request comment triggers. |
| `GITLAB_CLIENT_SECRET` | Optional | GitLab OAuth application secret for personal account linking and merge request comment triggers. |
| `GITLAB_WEBHOOK_SIGNING_TOKEN` | Optional | GitLab webhook signing token. |
| `GITLAB_WEBHOOK_SECRET` | Optional | GitLab webhook secret. |
| `GITEA_BASE_URL` | Gitea | Gitea base URL. |
| `GITEA_TOKEN` | Gitea | Gitea access token. |
| `GITEA_USERNAME` | Optional | Gitea username. |
| `GITEA_CLIENT_ID` | Optional | Gitea OAuth client ID. |
| `GITEA_CLIENT_SECRET` | Optional | Gitea OAuth client secret. |
| `GITEA_WEBHOOK_SECRET` | Optional | Gitea webhook secret. |
| `BITBUCKET_TOKEN` | Bitbucket | Atlassian API token with Bitbucket scopes. |
| `BITBUCKET_USERNAME` | Bitbucket | Atlassian account email that owns the API token. |
| `BITBUCKET_BASE_URL` | Optional | Bitbucket base URL. Defaults to `https://bitbucket.org` (Cloud only). |
| `BITBUCKET_CLIENT_ID` | Optional | Bitbucket OAuth client ID for personal account linking. |
| `BITBUCKET_CLIENT_SECRET` | Optional | Bitbucket OAuth client secret for personal account linking. |
| `BITBUCKET_WEBHOOK_SECRET` | Optional | Bitbucket webhook secret. |
| `ADO_ORGANIZATION` | Azure DevOps | Azure DevOps organization. |
| `ADO_TOKEN` | Azure DevOps | Azure DevOps access token. |
| `ADO_BASE_URL` | Optional | Azure DevOps base URL. |
| `ADO_USERNAME` | Optional | Azure DevOps username. |
| `ADO_CLIENT_ID` | Optional | Microsoft Entra client ID for Azure DevOps OAuth. Falls back to `R_MICROSOFT_CLIENT_ID`. |
| `ADO_CLIENT_SECRET` | Optional | Microsoft Entra client secret for Azure DevOps OAuth. Falls back to `R_MICROSOFT_CLIENT_SECRET`. |
| `ADO_TENANT_ID` | Conditional | Microsoft Entra tenant ID for Azure DevOps OAuth. Required unless the app is multi-tenant; falls back to `R_MICROSOFT_TENANT_ID`, then `common`. |
| `ADO_WEBHOOK_SECRET` | Optional | Azure DevOps webhook secret. |

### Communications and sign-in

Expand Down Expand Up @@ -294,7 +294,7 @@ as per-task auth tokens or workspace paths.
| `R_SLACK_CLIENT_SECRET` | Slack sign-in | Slack sign-in client secret. `R_SLACK_CLIENT_SECRET` is also accepted. |
| `R_MICROSOFT_CLIENT_ID` | Microsoft sign-in | Microsoft OAuth client ID. |
| `R_MICROSOFT_CLIENT_SECRET` | Microsoft sign-in | Microsoft OAuth client secret. |
| `R_MICROSOFT_TENANT_ID` | Microsoft sign-in | Microsoft tenant ID. Also accepted as the Azure DevOps tenant ID fallback. |
| `R_MICROSOFT_TENANT_ID` | Microsoft sign-in | Microsoft tenant ID. |
| `R_ALLOWED_EMAILS` | Optional | Comma-separated email allowlist for deployments that restrict sign-in by email. |

### Integrations
Expand Down
61 changes: 49 additions & 12 deletions apps/docs/providers/source-control/azure-devops.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,15 @@
---
title: Azure DevOps
icon: 'https://api.iconify.design/simple-icons:azuredevops.svg?color=currentColor'
description: Configure Azure DevOps repository sync for Roomote.
description: Connect Azure DevOps repositories and user accounts to Roomote.
---

Azure DevOps support uses a deployment-owned personal access token and
organization. There is no self-serve OAuth installation flow, service hook
ingestion, or Review Code automation path yet, so an operator provides Azure
DevOps credentials and syncs repositories from Settings.
Azure DevOps uses two separate credentials:

- a deployment-owned personal access token (PAT) lets Roomote sync and work in
repositories
- Microsoft Entra OAuth identifies individual Roomote users when they start
work from pull request comments

## Create an Azure DevOps PAT

Expand All @@ -34,6 +36,45 @@ ADO_USERNAME=ado
`ADO_BASE_URL` defaults to `https://dev.azure.com`. `ADO_USERNAME` defaults to
`ado` and is used as the Git-over-HTTPS username paired with the PAT.

## Link individual user accounts

Roomote requires account linking when setting up Azure DevOps Services so the
integration is ready for pull request comment triggers. Azure DevOps Server
uses the PAT flow without Microsoft Entra account linking.

1. Open [Microsoft Entra app registrations](https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)
and create or select an app registration.
2. Add this **Web** redirect URI, replacing the origin with your Roomote URL:

```text
https://<your-roomote-origin>/api/auth/oauth2/callback/ado
```

3. Under **API permissions**, add the Azure DevOps delegated
`user_impersonation` permission.
4. For a new app, create a client secret, then enter the application ID and
secret in the Azure DevOps account-linking section during setup or in
Settings.
5. Select **Save and link account** and complete Microsoft sign-in.

If Microsoft Teams or Microsoft sign-in is already configured, you can reuse
that Microsoft Entra app registration. Add the Azure DevOps redirect URI and
permission to the existing app. Roomote automatically reuses the stored
Microsoft client ID, client secret, and tenant ID when Azure DevOps-specific
values are not configured, so you do not need to re-enter the secret.

The equivalent environment variables are:

```sh
ADO_CLIENT_ID=<microsoft-entra-application-id>
ADO_CLIENT_SECRET=<microsoft-entra-client-secret>
ADO_TENANT_ID=<microsoft-entra-tenant-id>
```

`ADO_TENANT_ID` is required unless the Entra app supports multiple tenants. It
reuses `R_MICROSOFT_TENANT_ID` when available, then defaults to Microsoft&apos;s
`common` tenant for multi-tenant apps.

## Sync repositories

After the Azure DevOps values are available, open Settings, go to the
Expand All @@ -44,22 +85,18 @@ button. Roomote lists repositories from:
https://dev.azure.com/<organization>/_apis/git/repositories?api-version=7.1
```

Roomote stores the results as Azure DevOps repository rows.
Roomote stores the results as Azure DevOps repository rows and configures pull
request service hooks when the deployment has a publicly reachable URL.

Azure DevOps-backed tasks clone from the synced repository row, so sync must
run before launching an Azure DevOps-backed task. Worker tasks write
host- and clone-path-scoped Azure DevOps credentials into the file-backed Git
credential helper instead of exporting `ADO_TOKEN` into task shells.

## Current limits

Azure DevOps service hook ingestion and Review Code automation are not
implemented yet. Azure DevOps support currently covers repository sync and
Azure DevOps-backed manual or environment launches.

## Verify setup

1. sync Azure DevOps repositories from Settings
2. create or update an environment from a synced repository
3. start a small task and confirm Roomote can clone the repository
4. confirm Roomote can push a branch when the task produces changes
5. for Azure DevOps Services, trigger a small task from a pull request comment
Loading
Loading