Dev Box: de-duplicate how-to content and link to authoritative sources

RoseHJM · RoseHJM · commit 591275d2fc6c · 2026-02-09T10:28:39.000-08:00
- Removes duplicated permissions/comparison content from how-tos
- Links to concept-what-are-dev-box-customizations.md#permissions-for-customizations
- Updates catalog and Key Vault guidance links
- Adds ai-usage metadata where applicable
diff --git a/articles/dev-box/how-to-configure-customization-tasks.md b/articles/dev-box/how-to-configure-customization-tasks.md
@@ -6,8 +6,9 @@ ms.author: rosemalcolm
 ms.service: dev-box
 ms.custom:
   - ignite-2024
+  - ai-usage: ai-assisted
 ms.topic: how-to
-ms.date: 11/05/2024
+ms.date: 02/06/2026
 
 #customer intent: As a Dev Center Admin or Project Admin, I want to create additional tasks in a catalog so that I can create a specific customization in a customization or image definition file.
 ---
@@ -23,9 +24,7 @@ To complete the steps in this article, you must have:
 - A dev center configured with a dev box project.
 - An existing catalog in GitHub or Azure Repos.
 
-## Permissions required to configure customizations
-  
-[!INCLUDE [permissions-for-customizations](includes/permissions-for-customizations.md)]
+For permissions required to configure customizations, see [Permissions for customizations](concept-what-are-dev-box-customizations.md#permissions-for-customizations).
 
 ## What are tasks?
 
@@ -57,27 +56,18 @@ To create and manage tasks for Dev Box team customizations, follow these steps:
 
 1. Attach your repository to your dev center as a catalog.
 
-1. Create a configuration file for those tasks by following the steps in [Write a customization file](./how-to-write-customization-file.md).
+1. Create a configuration file for those tasks by following the steps in [Configure team customizations](how-to-configure-team-customizations.md).
 
 ### Use secrets from an Azure key vault
 
-You can use secrets from your Azure key vault in your YAML configurations to clone private repositories, or with any custom task you author that requires an access token.
-
-Your dev center needs access to your key vault. DevCenter doesn't support service tags, so if your key vault is kept private, you must allow trusted Microsoft services to bypass the firewall.
-
-To configure your key vault secrets for use in your YAML configurations:
-
-1. Ensure that your dev center project's managed identity has the Key Vault Reader role and Key Vault Secrets User role on your key vault.
-
-1. Grant the Key Vault Secrets User role for the key vault secret to each user or user group that should be able to consume the secret during the customization of a dev box. The user or group granted the role must include the managed identity for the dev center, your own user account, and any user or group that needs the secret during the customization of a dev box.
-
-For more information on using key vault secrets in a customization file, see [Clone a private repository by using a customization file](how-to-customizations-connect-resource-repository.md#use-key-vault-secrets-in-customization-files).
+You can use secrets from your Azure key vault in your YAML configurations to clone private repositories or run tasks that require an access token. For detailed configuration steps and examples, see [Connect to Azure resources or clone private repositories](how-to-customizations-connect-resource-repository.md).
 
 ## Attach a catalog
 
-You can attach a catalog to a project to make tasks accessible to the developer team. To attach a catalog to a project, follow the steps in [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
+You can attach a catalog to a project to make tasks accessible to the developer team. To attach a catalog to a project, follow the steps in [Add and manage catalogs in Microsoft Dev Box](how-to-configure-catalog.md).
 
 ## Related content
 
 - [Microsoft Dev Box customizations](concept-what-are-dev-box-customizations.md)
-- [Write a customization file for a dev box](./how-to-write-customization-file.md)
+- [Configure team customizations](how-to-configure-team-customizations.md)
+- [Customizations schema reference](reference-dev-box-customizations.md)
diff --git a/articles/dev-box/how-to-configure-dev-center-imaging.md b/articles/dev-box/how-to-configure-dev-center-imaging.md
@@ -7,8 +7,9 @@ ms.reviewer: rosemalcolm
 ms.service: dev-box
 ms.custom:
   - ignite-2024
+  - ai-usage: ai-assisted
 ms.topic: how-to
-ms.date: 11/11/2025
+ms.date: 02/06/2026
 
 #customer intent: As a Dev Center Admin or Project Admin, I want to configure dev box pools to use image definition files so that my development teams can create customized dev boxes.
 ---
@@ -25,53 +26,11 @@ In this article, you learn how to configure dev center imaging for your developm
 
 To complete the steps in this article, you need:
 
-- A team customization file that you want to use to create a dev box. If you don't have a customization file, see [Configure team customizations](how-to-configure-team-customizations.md).
+- A dev center with a project and dev box pool. If you don't have one, see [Configure Microsoft Dev Box](quickstart-configure-dev-box-service.md).
+- A catalog attached to your project with image definitions. If you don't have a catalog, see [Add and manage catalogs](how-to-configure-catalog.md).
+- A team customization file (image definition) in your catalog. If you don't have one, see [Configure team customizations](how-to-configure-team-customizations.md).
 
-## Permissions required to configure customizations
-  
-To perform the required actions for creating and applying customizations to a dev box, you need the following permissions:
-
-| Action | Permission/Role |
-| --- | --- |
-| Enable project-level catalogs for a dev center. | Platform engineer with write access on the subscription. |
-| Enable catalog sync settings for a project. | Platform engineer with write access on the subscription. |
-| Attach a catalog to a project. | Project Admin or Contributor permissions on the project. |
-| Add tasks to a catalog. | Permission to add to the repository that hosts the catalog. |
-
-To manage a dev box pool, you need the following permissions:
-
-| Action | Permission |
-|---|---|
-| Create, delete, or update a dev box pool. | - Owner or Contributor permissions on an Azure subscription or a specific resource group. </br>- DevCenter Owner permissions on the dev center. </br>- DevCenter Project Admin permissions for the project. |
-
-## Enable project-level catalogs
-
-To attach a catalog to a project, you must enable project-level catalogs. For more information, see [Add and manage catalogs in Microsoft Dev Box](how-to-configure-catalog.md).
-
-## Configure catalog sync settings for the project
-
-1. Sign in to the [Azure portal](https://portal.azure.com).
-1. In the search box, enter **projects**. In the list of results, select **Projects**.
-1. Open the Dev Box project for which you want to configure catalog sync settings.
-1. Select **Catalogs**.
-1. Select **Sync settings**.
-
-   :::image type="content" source="./media/how-to-configure-dev-center-imaging/customizations-project-sync-settings-small.png" alt-text="Screenshot of the Catalogs pane in the Azure portal, with the button for sync settings highlighted." lightbox="./media/how-to-configure-dev-center-imaging/customizations-project-sync-settings.png":::
-
-1. On the **Sync settings** pane, select **Image definitions**, then select **Save**.
-
-   :::image type="content" source="./media/how-to-configure-dev-center-imaging/customizations-project-sync-image-definitions.png" alt-text="Screenshot of the pane for sync settings in the Azure portal, with the checkbox for image definitions highlighted." lightbox="./media/how-to-configure-dev-center-imaging/customizations-project-sync-image-definitions.png":::
-
-## Attach a catalog that contains the definition file
-
-Before you can use a customization file as an image definition, attach a catalog that contains the definition file to your project. The catalog can be from GitHub or Azure Repos. For more information, see [Add and configure a catalog from GitHub or Azure Repos](../dev-box/how-to-configure-catalog.md).
-
-> [!NOTE]
-> Image definitions are only supported at the project level. You must attach catalogs containing image definitions to a project, not to a dev center.
-
-The **Image definitions** pane lists the image definitions that your project can access.
-
-:::image type="content" source="media/how-to-configure-dev-center-imaging/team-customizations-image-definitions-small.png" alt-text="Screenshot of the Azure portal pane that lists accessible image definitions for a project." lightbox="media/how-to-configure-dev-center-imaging/team-customizations-image-definitions.png":::
+For permissions required to configure customizations, see [Permissions for customizations](concept-what-are-dev-box-customizations.md#permissions-for-customizations).
 
 ## Build a reusable image
 
@@ -170,63 +129,20 @@ During the image build process, Dev Box creates a temporary storage account in y
 
 ## Configure a dev box pool to use an image definition
 
-To make customizations available to your development teams, configure a dev box pool to use an image definition. Store the customization file (imagedefinition.yaml) in a repository linked to a catalog in your project. When you specify the image definition for the pool, the customizations are applied to new dev boxes.
-
-### Create a dev box pool
+To use an image definition, you must configure a dev box pool to reference it. When developers create dev boxes from the pool, the customizations from the image definition are applied automatically.
 
-In Microsoft Dev Box, a dev box pool is a collection of dev boxes that you manage together. You must have at least one dev box pool before users can create a dev box. 
+For detailed steps on creating a dev box pool with an image definition, see [Configure a dev box pool to use an image definition](how-to-configure-team-customizations.md#configure-a-dev-box-pool-to-use-an-image-definition).
 
-The following steps show you how to create a dev box pool in a project. 
-
-If you don't have an available dev center and project, follow the steps in [Quickstart: Configure Microsoft Dev Box](quickstart-configure-dev-box-service.md) to create them.
-
-1. Sign in to the [Azure portal](https://portal.azure.com).
-
-1. In the search box, enter **projects**. In the list of results, select **Projects**.
-
-1. Open the project where you want to create the dev box pool.
-  
-   :::image type="content" source="./media/quickstart-configure-dev-box-service/select-project.png" alt-text="Screenshot that shows the list of existing projects." lightbox="./media/quickstart-configure-dev-box-service/select-project.png":::
-
-1. Select **Dev box pools**, then select **Create**.
-
-   :::image type="content" source="./media/quickstart-configure-dev-box-service/create-pool.png" alt-text="Screenshot of an empty list of dev box pools within a project, along with selections to start creating a pool." lightbox="./media/quickstart-configure-dev-box-service/create-pool.png":::
-
-1. On the **Create a dev box pool** pane, on the **Basics** tab, enter the following values:
-
-   | Setting | Value |
-   |---|---|
-   | **Name** | Enter a name for the pool. The pool name is visible to developers to select when they're creating dev boxes. The name must be unique within a project. |
-   | **Definition** | Select an **Image definition**. |
-   | **Compute** | Select the virtual machine size for the dev boxes in this pool. |
-   | **Storage** | Select the storage size for the dev boxes in this pool. |
-   | **Hibernation** | Shows whether hibernation is supported or not. |
-   | **Region** |  |
-   | **Network connection** | 1. Select **Deploy to a Microsoft hosted network**. </br>2. Select your desired deployment region for the dev boxes. Choose a region close to your expected dev box users for the optimal user experience. |
-   | **Licensing** | Select this checkbox to confirm that your organization has Azure Hybrid Benefit licenses that you want to apply to the dev boxes in this pool. |
-
-   :::image type="content" source="./media/how-to-configure-dev-center-imaging/dev-box-pool-create-basics-hibernation-image.png" alt-text="Screenshot of the Basics pane for creating a dev box pool." lightbox="./media/how-to-configure-dev-center-imaging/dev-box-pool-create-basics-hibernation-image.png":::
-
-1. Select **Create**.
-
-#### Hibernation support for dev boxes
+### Hibernation support
 
 Dev Box supports hibernation when both these conditions are met:
 - The source image defined in the image definition supports hibernation.
 - The compute resources of the dev box pool support hibernation.
 
-If either the image or the pool doesn't support hibernation, the feature isn't available for dev boxes in that pool. If hibernation isn't supported, verify that the base image specified in your image definition is created with hibernation support and that the pool uses that image definition.
-
-For more information about Dev Box support for hibernation, see [Configure hibernation in Microsoft Dev Box](how-to-configure-dev-box-hibernation.md).
-
-### Create a dev box by using the developer portal
-
-To verify that customizations are applied correctly, create a dev box in the Microsoft Dev Box developer portal. Follow the steps in [Quickstart: Create and connect to a dev box by using the Microsoft Dev Box developer portal](quickstart-create-dev-box.md), then connect to the newly created dev box and verify that the customizations work as expected.
-
-You can make adjustments to the image definition and create a new dev box to test the changes. When the customizations are correct, you can build a reusable image from the image definition.
+For more information, see [Configure hibernation in Microsoft Dev Box](how-to-configure-dev-box-hibernation.md).
 
 ## Related content
 
 - [Microsoft Dev Box customizations](concept-what-are-dev-box-customizations.md)
-- [Write a customization file for a dev box](./how-to-write-customization-file.md)
-- [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md)
+- [Configure team customizations](how-to-configure-team-customizations.md)
+- [Add and configure a catalog from GitHub or Azure Repos](how-to-configure-catalog.md)
diff --git a/articles/dev-box/how-to-configure-user-customizations.md b/articles/dev-box/how-to-configure-user-customizations.md
@@ -11,27 +11,19 @@ ms.custom:
   - ai-gen-title
   - ai-seo-date:04/19/2025
   - ai-gen-description
+  - ai-usage: ai-assisted
 ms.topic: how-to
-ms.date: 08/15/2025
+ms.date: 02/06/2026
 ---
 
 
 # Configure user customizations for dev boxes
 
 You can personalize your Microsoft Dev Box by uploading a user customization file. User customization files let you configure your dev box with your preferred personal settings and apps, so you can start coding faster. This article explains how to create, test, and upload a user customization file from your local drive or repository using Visual Studio (VS) Code. You also learn how to validate your file and manage customization settings for projects.
 
-Use customizations in Microsoft Dev Box in two ways: team customizations create a shared configuration for a team, and user customizations create a personal configuration for an individual developer. The following table shows the differences between the two types of customizations.
+Dev Box customizations work in two ways: team customizations create shared configurations for teams, and user customizations create personal configurations for individual developers. For a detailed comparison, see [Microsoft Dev Box customizations](concept-what-are-dev-box-customizations.md).
 
-| Feature                     | Team customizations       | User customizations                  |
-|-----------------------------|---------------------------|--------------------------------------|
-| Set up on                   | Dev box pool              | Dev box                              |
-| Customizations apply to     | All dev boxes in pool     | Individual dev box                   |
-| Easily shareable            | Yes                       | No                                   |
-| Customizations file name    | Imagedefinition.yaml      | *myfilename.yaml* or *workload.yaml* |
-| Source                      | Catalog                   | Upload or personal repository        |
-| Supports key vault secrets  | Yes                       | Yes                                  |
-
-User customizations help ensure that developers comply with company guardrails; only tasks custom tasks preapproved through a catalog are available to developers to use in their customization files. Standard dev box users can't run built-in PowerShell and WinGet tasks in a system context, which prevents privilege escalation. 
+User customizations help ensure that developers comply with company guardrails; only tasks preapproved through a catalog are available to developers. Standard dev box users can't run built-in PowerShell and WinGet tasks in a system context, which prevents privilege escalation. 
 
 User customizations can be enabled or disabled at the project level. When you create a project, user customizations are on by default.
 
@@ -42,18 +34,9 @@ To complete the steps in this article:
 
 - Set up a [dev center with a dev box definition, dev box pool, and dev box project](./quickstart-configure-dev-box-service.md) so you can create a dev box.
 - Join the Dev Box Users security group for at least one project.
-- Attach a catalog to the dev center with tasks you use in your customization file. If you don't have a catalog, see [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
-
-
-## Permissions required to set up customizations
-
-To create and apply customizations to a dev box, you need the following permissions:
+- Attach a catalog to the dev center with tasks you use in your customization file. If you don't have a catalog, see [Add and manage catalogs in Microsoft Dev Box](how-to-configure-catalog.md).
 
-| Action                                             | Permission or role       |
-|----------------------------------------------------|-------------------------|
-| Enable or disable user customizations on a project | Write permission on the project. |
-| Create a customization file                        | None specified. Anyone can create a customization file. |
-| Use the developer portal to upload and apply a YAML file during dev box creation | Dev Box User           |
+For permissions required to configure customizations, see [Permissions for customizations](concept-what-are-dev-box-customizations.md#permissions-for-customizations).
 
 ## Create a user customization file
 
@@ -186,4 +169,4 @@ If you create a dev box with user customizations in a project where user customi
 
 - [Microsoft Dev Box customizations](concept-what-are-dev-box-customizations.md)
 - [Configure dev center imaging](how-to-configure-dev-center-imaging.md)
-- [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md)
+- [Add and manage catalogs in Microsoft Dev Box](how-to-configure-catalog.md)
diff --git a/articles/dev-box/how-to-customizations-connect-resource-repository.md b/articles/dev-box/how-to-customizations-connect-resource-repository.md
@@ -11,8 +11,9 @@ ms.custom:
   - ai-gen-title
   - ai-seo-date:05/10/2025
   - ai-gen-description
+  - ai-usage: ai-assisted
 ms.topic: how-to
-ms.date: 09/26/2025
+ms.date: 02/06/2026
 ---
 
 # Securely connect to Azure resources or clone private repositories
@@ -207,5 +208,5 @@ For details on how to add users to DevOps organizations, see [Add organization u
 ## Related content
 
 - Learn how to [Set and retrieve a secret from Azure Key Vault using the Azure portal](/azure/key-vault/secrets/quick-create-portal).
-- Learn how to [Add and configure a catalog from GitHub or Azure Repos](../deployment-environments/how-to-configure-catalog.md).
+- Learn how to [Add and manage catalogs in Microsoft Dev Box](how-to-configure-catalog.md).
 - Learn how to [Use service principals & managed identities in Azure DevOps](/azure/devops/integrate/get-started/authentication/service-principal-managed-identity).
