Merge pull request #311571 from RoseHJM/devbox-howtos-dedup-links

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

Author: JamesJBarnett

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.
 ---
@@ -16,19 +17,6 @@ ms.date: 11/05/2024
 
 When you create tasks for Microsoft Dev Box customizations, you can define specific actions for your dev boxes to help ensure a consistent and efficient development environment. Creating new tasks in a catalog allows you to define reusable components tailored to your development teams and add guardrails around the configurations that are possible. This article guides you through creating a catalog for customization tasks, adding tasks, and attaching the catalog to a dev center or project.
 
-## Prerequisites
-
-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)]
-
-## What are tasks?
-
 A task performs a specific action, like installing software. Each task consists of one or more PowerShell scripts, along with a task.yaml file that provides parameters and defines how the scripts run. You can also include a PowerShell command in the task.yaml file.
 
 You can store a collection of curated tasks in a catalog attached to your dev center, with each task in a separate folder. Dev Box supports using a GitHub repository or an Azure Repos repository as a catalog. Dev Box scans a specified folder of the catalog recursively to find task definitions.
@@ -43,6 +31,15 @@ Microsoft provides a quickstart catalog to help you get started with customizati
 - Configure applications like installing Visual Studio extensions.
 - Run PowerShell scripts.
 
+## Prerequisites
+
+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.
+
+For permissions required to configure customizations, see [Permissions for customizations](concept-what-are-dev-box-customizations.md#permissions-for-customizations).
+
 ## Create tasks in a catalog
 
 Tasks, such as installing software or running scripts, are organized into a catalog. You create and manage tasks in a catalog, define new tasks, and attach your catalog to a dev center. With Microsoft's quickstart catalog, you can get started with common tasks like installing software, deploying DSC, cloning repositories, and configuring applications.
@@ -57,27 +54,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)

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
 
@@ -168,65 +127,24 @@ During the image build process, Dev Box creates a temporary storage account in y
 > [!IMPORTANT]
 > When an image is built from an image definition, a dev box is created to apply all the customizations and generate an image. By default, if no custom network is configured at the image definition level, the dev box is connected to a virtual network that Microsoft manages. Use the [network configuration](./reference-dev-box-customizations.md#networkconnection) property in image definitions for tasks that need access to on-premises or private resources to ensure that image generation is successful.
 
-## 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
-
-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. 
-
-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. |
+## Configure a dev box pool to use an image definition
 
-   :::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":::
+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.
 
-1. Select **Create**.
+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).
 
-#### 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)

articles/dev-box/how-to-configure-team-customizations.md

@@ -206,6 +206,9 @@ Set up your project to sync image definitions from the catalog. This setting let
 
 To use an image definition file, attach the catalog containing the file to your project. This makes the image definition available for selection when configuring your dev box pools.
 
+> [!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 shows the image definitions your project can use.
 
 :::image type="content" source="media/how-to-configure-team-customizations/team-customizations-image-definitions-small.png" alt-text="Screenshot of the Azure portal pane showing image definitions available for a project.":::