You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Streamline Your Workflow with Dev Box customizations
2
+
title: Streamline Your Workflow with Dev Box Customizations
3
3
description: Understand how to use Dev Box customizations to create ready-to-code configurations for your development teams and individual developers.
4
4
author: RoseHJM
5
5
ms.author: rosemalcolm
@@ -9,62 +9,64 @@ ms.custom:
9
9
ms.topic: concept-article
10
10
ms.date: 05/10/2025
11
11
12
-
#customer intent: As a Dev Center Admin or Project Admin, I want to understand how to use Dev Box customizations so that I can create efficient, ready-to-code configurations for my development teams.
12
+
#customer intent: As a Dev Center admin or project admin, I want to understand how to use Dev Box customizations so that I can create efficient, ready-to-code configurations for my development teams.
Getting developers started on a new project or team is often complex and time consuming. The Microsoft Dev Box customizations feature helps you streamline the setup of the developer environment. With customizations, you can configure ready-to-code workstations with the necessary applications, tools, repositories, code libraries, packages, and build scripts.
19
+
Getting developers started on a new project or with a new team is often complex and time consuming. The Microsoft Dev Box customizations feature helps you streamline the setup of the developer environment. With customizations, you can configure ready-to-code workstations with the necessary applications, tools, repositories, code libraries, packages, and build scripts.
21
20
22
21
Dev Box customizations let you:
22
+
23
23
- Install the necessary tools and applications.
24
24
- Enforce organizational security policies.
25
25
- Ensure consistency across dev boxes.
26
26
27
-
Microsoft Dev Box offers two ways to use customizations.
28
-
29
-
-*Team customizations* create a standard shared configuration for a team of developers in place of creating multiple standard or *golden* images for your teams.
27
+
Dev Box offers two ways to use customizations:
30
28
31
-
-*User customizations* enable developers to create a configuration for their personal preferences. User customizations enable developers to store their configuration in a file and run it when they create a dev box, providing consistency across all their dev boxes.
29
+
-**Team customizations**: Used to create a standard shared configuration for a team of developers in place of creating multiple standard or *golden* images for your teams.
30
+
-**User customizations**: Used by developers to create configurations for their personal preferences. With user customizations, developers can store their configurations in files and run them when they create dev boxes. Customizations provide consistency across all dev boxes.
32
31
33
32
| Feature | Team customizations | User customizations |
| Sourced from | Catalog or personal repository | Uploaded or from personal repository |
39
+
| Supports key vault secrets | Yes | Yes |
41
40
42
41
## What is a customization file?
43
42
44
-
Dev Box customizations use a YAML-formatted file to specify a list of tasks to apply from the dev center or a catalog when developers create a dev box. These tasks identify the catalog task and provide parameters like the name of the software to install. Developers can create their own customization files or use a shared customization file.
43
+
Dev Box customizations use a YAML-formatted file to specify a list of tasks to apply from the dev center or a catalog when developers create a dev box. These tasks identify the catalog task and provide parameters like the name of the software to install. Developers can create their own customization files or use a shared customization file.
45
44
46
-
You can use secrets from your Azure key vault in your customization file to clone private repositories, or with any custom task you author that requires an access token.
45
+
You can use secrets from your Azure key vault in your customization file to clone private repositories. You can also use them with any custom task that you author that requires an access token.
47
46
48
-
## What are tasks
47
+
## What are tasks?
49
48
50
-
Dev Box customization tasks are wrappers for PowerShell scripts. You use them to define reusable components that your teams can use in their customizations. WinGet and PowerShell tasks are available through the platform, and new ones can be added through a catalog. Tasks can run in either a system context or a user context after sign-in.
51
-
- Project admins define team customizations, which can use both custom and built-in tasks.
52
-
- User customizations can only use system tasks if the user is an administrator, or if the tasks are custom tasks preapproved by through a catalog. Standard dev box users can't run built-in PowerShell and WinGet tasks in a system context, which prevents privilege escalation.
49
+
Dev Box customization tasks are wrappers for PowerShell scripts. You use them to define reusable components that your teams can use in their customizations. WinGet and PowerShell tasks are available through the platform. You can add new ones through a catalog. Tasks can run in either a system context or a user context after sign-in.
53
50
54
-
When you create tasks, determine which need to run in a system context and which can run in a user context after sign-in.
51
+
- Project admins define team customizations, which can use both custom and built-in tasks.
52
+
- User customizations can use system tasks only if the user is an administrator, or if the tasks are custom tasks preapproved through a catalog. Standard dev box users can't run built-in PowerShell and WinGet tasks in a system context, which prevents privilege escalation.
53
+
54
+
When you create tasks, determine which ones need to run in a system context and which ones can run in a user context after sign-in.
55
55
56
56
## Differences between team customizations and user customizations
57
57
58
-
Dev Box team customizations allow developer team leads and IT admins to preconfigure customization files for dev box pools, eliminating the need for developers to go through manual setup.
58
+
Dev Box team customizations allow developer team leads and IT admins to preconfigure customization files for dev box pools. Customizations eliminate the need for developers to go through manual setup.
59
59
60
-
Microsoft recommends using team customizations to secure and standardize dev box deployments for a team. Sharing common YAML files among developer teams can be inefficient, lead to errors, and violate compliance policies.
60
+
We recommend that you use team customizations to secure and standardize Dev Box deployments for a team. Sharing common YAML files among developer teams can be inefficient, lead to errors, and violate compliance policies.
61
61
62
-
In addition to team customizations, individual developers can upload a customization file when they create their dev box to control the development environment. Developers should use individual customizations for personal settings and apps only.
62
+
In addition to team customizations, individual developers can upload a customization file when they create their dev box to control the development environment. Developers should use individual customizations for personal settings and apps only.
63
63
64
64
## How do customizations work?
65
-
Team customization and user customizations are both YAML-based files that specify a list of tasks to apply when creating a dev box. Select the appropriate tab to learn more about how each type of customization works.
65
+
66
+
Team customizations and user customizations are both YAML-based files that specify a list of tasks to apply when you create a dev box. Select the appropriate tab to learn more about how each type of customization works.
66
67
67
68
# [Team customizations](#tab/team-customizations)
69
+
68
70
### How do team customizations work?
69
71
70
72
You can use team customizations to define a shared Dev Box configuration for each of your development teams without having to invest in setting up an imaging solution like Packer or Azure virtual machine (VM) image templates. Team customizations provide a lightweight alternative that allows central platform engineering teams to delegate Dev Box configuration management to the teams that use them.
@@ -73,66 +75,66 @@ Team customizations also offer a built-in way to optimize your team's Dev Box cu
73
75
74
76
Configuring Dev Box team customizations for your organization requires careful planning and informed decision-making. The following diagram provides an overview of the process and highlights key decision points.
75
77
76
-
77
78
:::image type="content" source="media/concept-what-are-team-customizations/dev-box-customizations-workflow.svg" alt-text="Diagram that shows the workflow for Dev Box team customizations, including steps for planning, configuring, and deploying customizations." lightbox="media/concept-what-are-team-customizations/dev-box-customizations-workflow.svg":::
78
79
79
-
#### Configure your Dev Box service for team customizations
80
-
81
-
Set up your Dev Box service to support team customizations by following these steps:
82
-
83
-
1.**Configure your dev center:**
84
-
1. Enable project-level catalogs.
85
-
1. Assign permissions for project admins.
86
-
1.**Decide whether to use a catalog with custom reusable components:**
87
-
- Built-in (provided by the platform):
88
-
1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend starting with the built-in tasks.
89
-
- Your own catalog:
90
-
1. Host in Azure Repos or GitHub.
91
-
1. Add tasks.
92
-
1. Attach to a dev center.
93
-
1.**Create a YAML customization file:**
94
-
1. Create a customization file called imagedefinition.yaml.
95
-
1.**Specify an image in a dev box pool:**
96
-
1. Create or modify a dev box pool and specify imagedefinition.yaml as the image definition.
97
-
1.**Choose how to use the image definition:**
98
-
- Run the tasks in the image definition at the time of every dev box creation
99
-
- Optimize your image definition into a custom image.
100
-
1.**Create dev box:**
101
-
1. Create your dev box from the configured pool by using the developer portal.
102
-
103
-
To learn more about team customization and writing image definitions, see [Write an image definition file for Dev Box team customizations](how-to-write-image-definition-file.md).
80
+
#### Configure Dev Box for team customizations
81
+
82
+
To set up Dev Box to support team customizations, follow these steps:
83
+
84
+
1. Configure your dev center:
85
+
1. Enable project-level catalogs.
86
+
1. Assign permissions for project admins.
87
+
1. Decide whether to use a catalog with custom reusable components:
88
+
- Built-in (provided by the platform):
89
+
1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend that you start with the built-in tasks.
90
+
- Your own catalog:
91
+
1. Host in Azure Repos or GitHub.
92
+
1. Add tasks.
93
+
1. Attach to a dev center.
94
+
1. Create a YAML customization file called `imagedefinition.yaml`.
95
+
1. Specify an image in a dev box pool:
96
+
1. Create or modify a dev box pool.
97
+
1. Specify `imagedefinition.yaml` as the image definition.
98
+
1. Choose how to use the image definition:
99
+
- Run the tasks in the image definition at the time of every dev box creation.
100
+
- Optimize your image definition into a custom image.
101
+
1. Create your dev box from the configured pool by using the developer portal.
102
+
103
+
To learn more about team customization and writing image definitions, see [Write an image definition file for Dev Box team customizations](how-to-write-image-definition-file.md).
104
104
Then, to learn how to optimize your image definition into a custom image, see [Configure imaging for Dev Box team customizations](how-to-configure-customization-imaging.md).
105
105
106
106
# [User customizations](#tab/user-customizations)
107
+
107
108
### How do user customizations work?
108
-
Individual developers can attach a YAML-based customization file when creating their dev box to control the development environment. Developers use user customizations only for personal settings and apps.
109
+
110
+
Individual developers can attach a YAML-based customization file when they create their dev box to control the development environment. Developers use user customizations only for personal settings and apps.
109
111
110
112
:::image type="content" source="media/concept-what-are-team-customizations/dev-box-user-customizations-workflow.svg" alt-text="Diagram that shows the workflow for Dev Box user customizations, including steps for planning, configuring, and deploying customizations." lightbox="media/concept-what-are-team-customizations/dev-box-user-customizations-workflow.svg":::
111
113
112
-
#### Configure your Dev Box service for user customizations
114
+
#### Configure Dev Box for user customizations
115
+
116
+
To set up Dev Box to support user customizations, follow these steps:
113
117
114
-
To set up your Dev Box service to support user customizations, follow these steps:
118
+
1. Decide whether to use a catalog with custom reusable components:
119
+
- Built-in (provided by the platform):
120
+
1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend that you start with the built-in tasks.
121
+
- Your own catalog:
122
+
1. Host in Azure Repos or GitHub.
123
+
1. Add tasks.
124
+
1. Attach to a dev center.
125
+
1. Create a customization file.
126
+
1. Create a dev box:
127
+
1. Create your dev box from the configured pool by using the developer portal.
128
+
1. Upload and validate your customization file as you create your dev box.
115
129
116
-
1.**Decide whether to use a catalog with custom reusable components:**
117
-
1. Built-in (provided by the platform):
118
-
1. Use PowerShell or WinGet built-in tasks (starts with ~/). We recommend starting with the built-in tasks.
119
-
1. Your own catalog:
120
-
1. Host in Azure Repos or GitHub.
121
-
1. Add tasks.
122
-
1. Attach to a dev center.
123
-
1.**Create a customization file:**
124
-
1. Create a customization file.
125
-
1.**Create dev box:**
126
-
1. Create your dev box from the configured pool by using the developer portal.
127
-
1. Upload and validate your customization file as you create your dev box.
128
-
1. The dev box is created with customizations.
130
+
The dev box is created with customizations.
129
131
130
132
To learn more about user customizations, see [Write a user customization file for a dev box](how-to-write-user-customization-file.md).
131
133
132
134
---
133
135
134
136
## Related content
135
137
136
-
-[Quickstart: create a dev box by using team customizations](quickstart-team-customizations.md)
138
+
-[Quickstart: Create a dev box by using team customizations](quickstart-team-customizations.md)
137
139
-[Configure imaging for dev box team customizations](how-to-configure-customization-imaging.md)
0 commit comments