Merge pull request #30343 from awanlin/topic/visualstudio-domain-support

Added support for `{org}.visualstudio.com` domains used by Azure DevOps
2026-02-05 13:59:07 -06:00
parent b584aaa4e0 cc6206e436
commit 860b49df9a
9 changed files with 225 additions and 39 deletions
@@ -9,11 +9,7 @@ description: Automatically discovering catalog entities from repositories in an
 This documentation is written for [the new backend system](../../backend-system/index.md) which is the default since Backstage [version 1.24](../../releases/v1.24.0.md). If you are still on the old backend system, you may want to read [its own article](https://github.com/backstage/backstage/blob/v1.37.0/docs/integrations/azure/discovery--old.md) instead, and [consider migrating](../../backend-system/building-backends/08-migrating.md)!
 :::

-The Azure DevOps integration has a special entity provider for discovering
-catalog entities within an Azure DevOps. The provider will crawl your Azure
-DevOps organization and register entities matching the configured path. This can
-be useful as an alternative to static locations or manually adding things to the
-catalog.
+The Azure DevOps integration has a special entity provider for discovering catalog entities within an Azure DevOps. The provider will crawl your Azure DevOps organization and register entities matching the configured path. This can be useful as an alternative to static locations or manually adding things to the catalog.

 This guide explains how to install and configure the Azure DevOps Entity Provider (recommended) or the Azure DevOps Processor.

@@ -21,9 +17,7 @@ This guide explains how to install and configure the Azure DevOps Entity Provide

 ### Code Search Feature

-Azure discovery is driven by the Code Search feature in Azure DevOps, this may not be enabled by default. For Azure
-DevOps Services you can confirm this by looking at the installed extensions in your Organization Settings. For Azure
-DevOps Server you'll find this information in your Collection Settings.
+Azure discovery is driven by the Code Search feature in Azure DevOps, this may not be enabled by default. For Azure DevOps Services you can confirm this by looking at the installed extensions in your Organization Settings. For Azure DevOps Server you'll find this information in your Collection Settings.

 If the Code Search extension is not listed then you can install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms.vss-code-search&targetId=f9352dac-ba6e-434e-9241-a848a510ce3f&utm_source=vstsproduct&utm_medium=SearchExtStatus).

@@ -68,7 +62,7 @@ catalog:

 The parameters available are:

- **`host:`** _(optional)_ Leave empty for Cloud hosted, otherwise set to your self-hosted instance host.
+- **`host:`** _(optional)_ The default value is `dev.azure.com`, it is required for legacy `{org}.visualstudio.com` domains or for on-premise installations.
 - **`organization:`** Your Organization slug (or Collection for on-premise users). Required.
 - **`project:`** _(required)_ Your project slug. Wildcards are supported as shown on the examples above. Using '\*' will search all projects. For a project name containing spaces, use both single and double quotes as in `project: '"My Project Name"'`.
 - **`repository:`** _(optional)_ The repository name. Wildcards are supported as show on the examples above. If not set, all repositories will be searched.
@@ -200,6 +200,47 @@ However a system-assigned managed identity is the most secure option because:

 :::

+### Legacy `{org}.visualstudio.com` Domains
+
+Backstage supports the legacy `{org}.visualstudio.com` domains along with all the previously mentioned authentication options, the caveat is that each Azure DevOps Organization will need to be defined in your configuration along with a single credential.
+
+For example, this will work:
+
+```yaml
+integrations:
+  azure:
+    - host: my-org.visualstudio.com
+      credentials:
+        - clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
+```
+
+As will this:
+
+```yaml
+integrations:
+  azure:
+    - host: my-other-org.visualstudio.com
+      credentials:
+        - personalAccessToken: ${PERSONAL_ACCESS_TOKEN}
+```
+
+But this will NOT work:
+
+```yaml
+integrations:
+  azure:
+    - host: my-org.visualstudio.com
+      credentials:
+        - organizations:
+            - my-org
+            - my-other-org
+          clientId: ${AZURE_CLIENT_ID}
+          clientSecret: ${AZURE_CLIENT_SECRET}
+          tenantId: ${AZURE_TENANT_ID}
+```
+
 ## Configuration schema

 The configuration is a structure with these elements: