Getting Started

• 1: Prerequisites
• 1.1: Organization roles and responsabilities requirements
• 1.2: Framework and Tools requirements
• 2: Quick Start
• 3: Release Strategy

1 - Prerequisites

1.1 - Organization roles and responsabilities requirements

Overview

The Dev Box accelerator aligns with the requirements and responsibilities for each organizational role involved in deploying and using Microsoft Dev Box, with a focus on RBAC permissions and configuration prerequisites.

The roles covered include:

• Platform Engineers
• Development Team Leads
• Developers

Each role has distinct requirements to ensure a secure, scalable, and successful Dev Box deployment.

Platform Engineer Requirements

Platform Engineers are responsible for deploying and governing the core infrastructure that powers Microsoft Dev Box, including Dev Centers, network connections, and governance policies.

Responsibilities

• Create and configure Dev Centers and Projects
• Set up network connections (Microsoft-hosted or custom VNETs)
• Define Dev Box definitions (SKUs, base images)
• Apply RBAC roles and enforce policies
• Enable monitoring and diagnostics

Required Azure Roles

Additional Requirements

Development Team Lead Requirements

Development Team Leads manage the Dev Box experience for their teams by defining image configurations, Dev Box pools, and assigning users to environments.

Responsibilities

• Define Dev Box pools per team or project
• Customize and manage Dev Box definitions
• Assign users to Dev Box environments via Microsoft Entra ID groups
• Validate Dev Box readiness and configurations

Required Azure Roles

Additional Requirements

Developer Requirements

Developers are end users of Microsoft Dev Box and require access to preconfigured environments that match their team’s development stack.

Responsibilities

• Access and manage assigned Dev Boxes via the portal
• Use the Dev Box to develop, build, and test code
• Customize environment (if permitted) within constraints

Required Azure Roles

Summary

Before deploying or using the Dev Box accelerator, ensure each role has the following:

• Platform Engineers: Subscription access, network configuration, Dev Center ownership, and monitoring setup
• Team Leads: RBAC permissions, Dev Box definitions and pools, image strategy, and group assignments
• Developers: Assigned Entra ID group, portal access, and an understanding of the configured environment

For RBAC setup instructions, see:
Assign roles using Azure portal

1.2 - Framework and Tools requirements

Overview

This document provides a reference table for key Azure development tools, along with direct links to their official documentation and installation guides.

How to Install

Windows (via PowerShell and winget)

# Azure CLI
winget install --id Microsoft.AzureCLI

# Azure Developer CLI
winget install --id Microsoft.AzureDeveloperCLI

# Bicep CLI (requires Azure CLI)
az bicep install

# Visual Studio Code
winget install --id Microsoft.VisualStudioCode

Ubuntu (via Bash)

# Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# Azure Developer CLI
curl -fsSL https://aka.ms/install-azd.sh | bash

# Bicep CLI (requires Azure CLI)
az bicep install

# Visual Studio Code
sudo apt update
sudo apt install wget gpg -y
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg
sudo install -o root -g root -m 644 packages.microsoft.gpg /etc/apt/keyrings/
sudo sh -c 'echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/packages.microsoft.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list'
sudo apt update
sudo apt install code -y

2 - Quick Start

This guide will help you quickly deploy the Dev Box accelerator in your Azure environment for evaluation and testing purposes.

Installation

Step 1: Fork the Required GitHub Repositories

Begin by forking the necessary GitHub repositories to your account.

# Dev Box accelerator repository
gh repo fork Evilazaro/DevExp-DevBox --clone --remote

# Identity Provider solution demo repository
gh repo fork Evilazaro/IdentityProvider --clone --remote

# eShop solution demo repository
gh repo fork Evilazaro/eShop --clone --remote

Step 2: Initialize Your Local Environment

Navigate to your cloned Dev Box repository directory and initialize the environment:

Windows (PowerShell)

# Change to recommended region for your location
$location = "eastus2"
$envName = "prod"

# Verify GitHub authentication
if (-not (gh auth status 2>&1 | Select-String "Logged in")) {
    Write-Host "Please login to GitHub first with 'gh auth login'" -ForegroundColor Red
    exit 1
}

# Create Azure Developer CLI environment
azd env new $envName --no-prompt

# Configure environment settings
Set-Content -Path ".\.azure\$envName\.env" -Value "AZURE_ENV_NAME='$envName'"

# Securely retrieve GitHub token
$pat = gh auth token
Add-Content -Path ".\.azure\$envName\.env" -Value "KEY_VAULT_SECRET='$pat'"
Add-Content -Path ".\.azure\$envName\.env" -Value "AZURE_LOCATION='$location'"

# Show current configuration (validates setup)
azd config show

Linux/macOS (Bash)

# Change to recommended region for your location
location="eastus2"
envName="prod"

# Verify GitHub authentication
if ! gh auth status &>/dev/null; then
    echo "Please login to GitHub first with 'gh auth login'"
    exit 1
fi

# Create Azure Developer CLI environment
azd env new "$envName" --no-prompt

# Configure environment settings
mkdir -p .azure/"$envName"
echo "AZURE_ENV_NAME='$envName'" > .azure/"$envName"/.env
pat=$(gh auth token)
echo "KEY_VAULT_SECRET='$pat'" >> .azure/"$envName"/.env
echo "AZURE_LOCATION='$location'" >> .azure/"$envName"/.env

# Show current configuration (validates setup)
azd config show

Step 3: Deploy the Accelerator

Once your environment is configured, deploy the accelerator:

# Deploy the accelerator
azd provision -e $envName

3 - Release Strategy

Overview

The Dev Box landing zone accelerator uses a branch-based semantic release strategy with intelligent overflow handling and conditional versioning rules. This approach ensures consistent, predictable releases while maintaining development flexibility across different branch types.

Build and Deploy Status

Release Strategy Summary

Branch-Specific Versioning Rules

🎯 Main Branch (main)

New Conditional Major Increment Rule:

• If minor = 0 AND patch = 0: Increment major version
  • Example: v1.0.0 → v2.0.0
• If minor ≠ 0 OR patch ≠ 0: Keep major version, increment patch
  • Example: v1.5.0 → v1.5.1
  • Example: v1.0.3 → v1.0.4
  • Example: v1.5.3 → v1.5.4

Overflow Handling:

• If patch exceeds 99: Reset patch to 0, increment minor
  • Example: v1.5.99 → v1.6.0
• If minor exceeds 99: Reset minor to 0, increment major
  • Example: v1.99.99 → v2.0.0

✨ Feature Branches (feature/**)

Patch Increment Strategy:

• Increments the patch version by the number of commits in the branch
• Format: vX.Y.(Z+commits)-feature.branch-name

Examples:

• Current: v1.2.5, Branch: feature/user-authentication, Commits: 3
• Result: v1.2.8-feature.user-authentication

Overflow Logic:

• If patch + commits > 99: Reset patch to 0, increment minor
• If minor overflow occurs: Reset minor to 0, increment major

🔧 Fix Branches (fix/**)

Minor Increment Strategy:

• Increments the minor version by the number of commits in the branch
• Format: vX.(Y+commits).Z-fix.branch-name

Examples:

• Current: v1.2.5, Branch: fix/login-bug, Commits: 2
• Result: v1.4.5-fix.login-bug

Overflow Logic:

• If minor + commits > 99: Reset minor to 0, increment major

Version Examples

Main Branch Scenarios

Feature Branch Scenarios

Fix Branch Scenarios

Release Notes Structure

Each release includes comprehensive documentation:

🌟 **Branch-Based Release Strategy with Conditional Major Increment**

🔀 **Branch**: `main`
🏷️ **Version**: `v2.0.0`
📦 **Previous Version**: `v1.0.0`
🚀 **Release Type**: `main`
🤖 **Trigger**: `Push`
📝 **Commit**: `abc123...`

## Release Strategy Applied
🎯 **Main Branch**: Conditional major increment (only if minor=0 AND patch=0)

## Main Branch Logic
- **If minor=0 AND patch=0**: Increment major → `major+1.0.0`
- **If minor≠0 OR patch≠0**: Keep major, increment patch → `major.minor.(patch+1)`
- **Overflow handling**: If patch > 99 → `minor+1, patch=0`

## Artifacts
- 📄 Bicep templates compiled to ARM templates
- 🏗️ Infrastructure deployment files
- 📋 Release metadata and documentation

Best Practices

For Developers

1. Branch Naming: Use descriptive branch names following the patterns:

   • feature/descriptive-name
   • fix/issue-description

2. Commit Strategy: Keep commits atomic and meaningful as they influence version calculations

3. Testing: Ensure all changes are tested before merging to main

For Release Management

1. Main Branch Protection: Only merge tested, reviewed code to main
2. Version Monitoring: Monitor version progression to prevent unexpected major increments
3. Release Planning: Use the conditional major increment rule for planned major releases