microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/customization/environment.md
335lines · modecode
| 1 | --- |
| 2 | title: Environment Customization |
| 3 | description: Configure DevContainers, VS Code settings, MCP servers, and coding agent environments for your team |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-06-11 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - devcontainer |
| 9 | - vs code settings |
| 10 | - mcp servers |
| 11 | - environment |
| 12 | estimated_reading_time: 6 |
| 13 | --- |
| 14 | |
| 15 | ## DevContainer Configuration |
| 16 | |
| 17 | HVE Core uses an Ubuntu 22.04 (Jammy) base image with Node.js 20, Python 3.11, |
| 18 | and PowerShell 7 pre-installed. The configuration lives in |
| 19 | `.devcontainer/devcontainer.json` and includes extensions for Markdown editing, |
| 20 | spell checking, and GitHub integration. |
| 21 | |
| 22 | ### Default Tool Stack |
| 23 | |
| 24 | The DevContainer ships with these tools: |
| 25 | |
| 26 | * Node.js 20 with npm |
| 27 | * Python 3.11 |
| 28 | * PowerShell 7 with PSScriptAnalyzer, PowerShell-Yaml, and Pester 5.7.1 |
| 29 | * Git and GitHub CLI |
| 30 | * Azure CLI |
| 31 | * shellcheck for bash validation |
| 32 | * actionlint for GitHub Actions workflow validation |
| 33 | * gitleaks for secret scanning |
| 34 | |
| 35 | ### Customizing for Your Team |
| 36 | |
| 37 | To add tools or adjust versions, modify `.devcontainer/devcontainer.json`. The |
| 38 | `features` section controls language runtimes and CLIs: |
| 39 | |
| 40 | ```json |
| 41 | { |
| 42 | "features": { |
| 43 | "ghcr.io/devcontainers/features/node:1": { |
| 44 | "version": "20" |
| 45 | }, |
| 46 | "ghcr.io/devcontainers/features/python:1": { |
| 47 | "version": "3.11" |
| 48 | }, |
| 49 | "ghcr.io/devcontainers/features/powershell:1": {} |
| 50 | } |
| 51 | } |
| 52 | ``` |
| 53 | |
| 54 | Add new features by referencing published DevContainer features from the |
| 55 | [DevContainers feature registry](https://containers.dev/features). For example, |
| 56 | to add Terraform: |
| 57 | |
| 58 | ```json |
| 59 | { |
| 60 | "features": { |
| 61 | "ghcr.io/devcontainers/features/terraform:1": { |
| 62 | "version": "1.6" |
| 63 | } |
| 64 | } |
| 65 | } |
| 66 | ``` |
| 67 | |
| 68 | ### Adding VS Code Extensions |
| 69 | |
| 70 | Include team-specific extensions in the `customizations.vscode.extensions` |
| 71 | array. Each entry uses the `publisher.extensionId` format: |
| 72 | |
| 73 | ```json |
| 74 | { |
| 75 | "customizations": { |
| 76 | "vscode": { |
| 77 | "extensions": [ |
| 78 | "streetsidesoftware.code-spell-checker", |
| 79 | "davidanson.vscode-markdownlint", |
| 80 | "ms-python.python" |
| 81 | ] |
| 82 | } |
| 83 | } |
| 84 | } |
| 85 | ``` |
| 86 | |
| 87 | ### Lifecycle Scripts |
| 88 | |
| 89 | Three lifecycle hooks execute during container setup: |
| 90 | |
| 91 | * `onCreateCommand` runs `.devcontainer/scripts/on-create.sh` to install system |
| 92 | dependencies (shellcheck, actionlint, PowerShell modules, gitleaks) |
| 93 | * `updateContentCommand` runs `npm ci` to install JavaScript dependencies |
| 94 | * `postCreateCommand` runs `.devcontainer/scripts/post-create.sh` for final |
| 95 | configuration |
| 96 | |
| 97 | Add custom setup steps to these scripts or create new scripts referenced from |
| 98 | `devcontainer.json`. |
| 99 | |
| 100 | ## VS Code Settings |
| 101 | |
| 102 | Workspace-level settings in `.vscode/settings.json` configure editor behavior, |
| 103 | Copilot customization discovery, and validation tools. These settings apply to |
| 104 | everyone who opens the workspace. |
| 105 | |
| 106 | ### Key Settings |
| 107 | |
| 108 | The workspace configures several critical behaviors: |
| 109 | |
| 110 | ```json |
| 111 | { |
| 112 | "editor.formatOnSave": true, |
| 113 | "[markdown]": { |
| 114 | "editor.defaultFormatter": "davidanson.vscode-markdownlint" |
| 115 | }, |
| 116 | "search.followSymlinks": false |
| 117 | } |
| 118 | ``` |
| 119 | |
| 120 | ### Copilot Discovery Paths |
| 121 | |
| 122 | VS Code discovers customization files through `chat.*FilesLocations` settings. |
| 123 | Each entry maps a directory path to `true` to enable scanning: |
| 124 | |
| 125 | ```json |
| 126 | { |
| 127 | "chat.instructionsFilesLocations": { |
| 128 | ".github/instructions/hve-core": true, |
| 129 | ".github/instructions/coding-standards": true |
| 130 | }, |
| 131 | "chat.agentFilesLocations": { |
| 132 | ".github/agents/hve-core": true, |
| 133 | ".github/agents/hve-core/subagents": true |
| 134 | }, |
| 135 | "chat.promptFilesLocations": { |
| 136 | ".github/prompts/hve-core": true |
| 137 | }, |
| 138 | "chat.agentSkillsLocations": { |
| 139 | ".github/skills": true, |
| 140 | ".github/skills/shared": true, |
| 141 | ".github/skills/coding-standards": true, |
| 142 | ".github/skills/design-thinking": true |
| 143 | } |
| 144 | } |
| 145 | ``` |
| 146 | |
| 147 | When you add a new collection directory, register it in these settings so Copilot |
| 148 | discovers your customizations. |
| 149 | |
| 150 | ### YAML Schema Validation |
| 151 | |
| 152 | The workspace maps YAML schemas to frontmatter validation: |
| 153 | |
| 154 | ```json |
| 155 | { |
| 156 | "yaml.schemas": { |
| 157 | "./scripts/linting/schemas/docs-frontmatter.schema.json": [ |
| 158 | "docs/**/*.md" |
| 159 | ] |
| 160 | } |
| 161 | } |
| 162 | ``` |
| 163 | |
| 164 | This setup provides in-editor validation for frontmatter fields when the Red Hat |
| 165 | YAML extension (`redhat.vscode-yaml`) is installed. |
| 166 | |
| 167 | ### Commit Message Instructions |
| 168 | |
| 169 | Copilot uses a dedicated instructions file for generating commit messages: |
| 170 | |
| 171 | ```json |
| 172 | { |
| 173 | "github.copilot.chat.commitMessageGeneration.instructions": [ |
| 174 | { |
| 175 | "file": ".github/instructions/hve-core/commit-message.instructions.md" |
| 176 | } |
| 177 | ] |
| 178 | } |
| 179 | ``` |
| 180 | |
| 181 | You can add your own commit message instructions file or replace this reference |
| 182 | to match your team's commit conventions. |
| 183 | |
| 184 | ## MCP Server Integration |
| 185 | |
| 186 | Model Context Protocol (MCP) servers extend Copilot's capabilities by connecting |
| 187 | it to external tools and data sources. MCP servers run alongside VS Code and |
| 188 | provide additional context, actions, or integrations that Copilot can invoke |
| 189 | during conversations. |
| 190 | |
| 191 | ### Configuration |
| 192 | |
| 193 | MCP servers are configured in `.vscode/mcp.json` at the workspace level: |
| 194 | |
| 195 | ```json |
| 196 | { |
| 197 | "servers": { |
| 198 | "github": { |
| 199 | "type": "http", |
| 200 | "url": "https://api.githubcopilot.com/mcp/" |
| 201 | } |
| 202 | } |
| 203 | } |
| 204 | ``` |
| 205 | |
| 206 | ### Adding Team-Specific MCP Servers |
| 207 | |
| 208 | To integrate your team's tools, add server entries to the `servers` object. |
| 209 | Each server needs a unique key, a type, and connection details: |
| 210 | |
| 211 | ```json |
| 212 | { |
| 213 | "servers": { |
| 214 | "github": { |
| 215 | "type": "http", |
| 216 | "url": "https://api.githubcopilot.com/mcp/" |
| 217 | }, |
| 218 | "contoso-api": { |
| 219 | "type": "http", |
| 220 | "url": "https://mcp.contoso.com/v1/" |
| 221 | } |
| 222 | } |
| 223 | } |
| 224 | ``` |
| 225 | |
| 226 | MCP servers enable agents to interact with issue trackers, CI/CD pipelines, |
| 227 | databases, and other systems your team relies on. |
| 228 | |
| 229 | ## Coding Agent Environment |
| 230 | |
| 231 | The GitHub Copilot coding agent runs in a cloud-based GitHub Actions environment, |
| 232 | separate from the local DevContainer. The |
| 233 | `.github/workflows/copilot-setup-steps.yml` workflow pre-installs tools before |
| 234 | the agent begins work. |
| 235 | |
| 236 | ### Pre-Installed Tools |
| 237 | |
| 238 | The coding agent environment includes: |
| 239 | |
| 240 | * Node.js 20 with npm dependencies from `package.json` |
| 241 | * Python 3.11 |
| 242 | * PowerShell 7 with PSScriptAnalyzer, PowerShell-Yaml, and Pester 5.7.1 |
| 243 | * shellcheck (pre-installed on ubuntu-latest) |
| 244 | * actionlint for GitHub Actions workflow validation |
| 245 | |
| 246 | ### Adding Tools for the Coding Agent |
| 247 | |
| 248 | Add installation steps to `copilot-setup-steps.yml`. Each tool should include |
| 249 | SHA-verified downloads for security: |
| 250 | |
| 251 | ```yaml |
| 252 | - name: Install custom tool |
| 253 | env: |
| 254 | TOOL_VERSION: '1.0.0' |
| 255 | TOOL_SHA256: 'abc123...' |
| 256 | run: | |
| 257 | curl -sLO "https://example.com/tool_${TOOL_VERSION}.tar.gz" |
| 258 | echo "${TOOL_SHA256} tool_${TOOL_VERSION}.tar.gz" | sha256sum -c - |
| 259 | tar -xzf "tool_${TOOL_VERSION}.tar.gz" tool |
| 260 | sudo install tool /usr/local/bin/tool |
| 261 | ``` |
| 262 | |
| 263 | ### Validation |
| 264 | |
| 265 | The workflow supports manual execution through `workflow_dispatch`, allowing you |
| 266 | to test setup changes before the coding agent encounters them. |
| 267 | |
| 268 | ## Environment Synchronization |
| 269 | |
| 270 | The DevContainer (`on-create.sh`) and coding agent (`copilot-setup-steps.yml`) |
| 271 | share most tools but differ intentionally in a few areas. |
| 272 | |
| 273 | ### Shared Tools |
| 274 | |
| 275 | | Tool | DevContainer | Coding Agent | |
| 276 | |------------------|--------------|--------------| |
| 277 | | Node.js 20 | Yes | Yes | |
| 278 | | Python 3.11 | Yes | Yes | |
| 279 | | PowerShell 7 | Yes | Yes | |
| 280 | | PSScriptAnalyzer | Yes | Yes | |
| 281 | | Pester 5.7.1 | Yes | Yes | |
| 282 | | shellcheck | Yes | Yes | |
| 283 | | actionlint | Yes | Yes | |
| 284 | |
| 285 | ### Intentional Differences |
| 286 | |
| 287 | | Tool | DevContainer | Coding Agent | Reason | |
| 288 | |----------|--------------|--------------|------------------------------------------------| |
| 289 | | gitleaks | Yes | No | Secret scanning is relevant for local dev only | |
| 290 | |
| 291 | ### Keeping Environments Aligned |
| 292 | |
| 293 | When adding or removing tools in either environment, evaluate whether both need |
| 294 | the change and update accordingly. Follow this checklist: |
| 295 | |
| 296 | 1. Determine if the tool is needed for local development, coding agent work, |
| 297 | or both. |
| 298 | 2. Update `.devcontainer/scripts/on-create.sh` for DevContainer changes. |
| 299 | 3. Update `.github/workflows/copilot-setup-steps.yml` for coding agent changes. |
| 300 | 4. Pin dependency versions and verify checksums in both locations. |
| 301 | 5. Test the DevContainer rebuild and run the setup workflow via |
| 302 | `workflow_dispatch`. |
| 303 | |
| 304 | ## Role Scenarios |
| 305 | |
| 306 | ### SRE/Operations |
| 307 | |
| 308 | An SRE team at Fabrikam needs Terraform and kubectl available in both |
| 309 | environments for infrastructure-as-code workflows. |
| 310 | |
| 311 | Steps to customize: |
| 312 | |
| 313 | 1. Add the Terraform DevContainer feature to `devcontainer.json` |
| 314 | 2. Add a kubectl installation step to `on-create.sh` |
| 315 | 3. Mirror both installations in `copilot-setup-steps.yml` |
| 316 | 4. Add the Terraform VS Code extension to the DevContainer extensions list |
| 317 | 5. Register any IaC-specific instruction paths in `.vscode/settings.json` |
| 318 | |
| 319 | ### Engineer |
| 320 | |
| 321 | A development team at Northwind Traders uses a custom API testing tool and wants |
| 322 | Copilot to reference their internal MCP server during code reviews. |
| 323 | |
| 324 | Steps to customize: |
| 325 | |
| 326 | 1. Add the API testing tool to `on-create.sh` and `copilot-setup-steps.yml` |
| 327 | 2. Configure the internal MCP server in `.vscode/mcp.json` |
| 328 | 3. Add workspace settings for any new extensions the team requires |
| 329 | 4. Create an instructions file that teaches Copilot about the team's API |
| 330 | conventions |
| 331 | |
| 332 | <!-- markdownlint-disable MD036 --> |
| 333 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 334 | then carefully refined by our team of discerning human reviewers.* |
| 335 | <!-- markdownlint-enable MD036 --> |
| 336 | |