GitVita
New repositoryImport repositoryNew issue
Your repositories Your dashboard Sign in

microsoft/hve-core

Public

mirrored fromhttps://github.com/microsoft/hve-coreAvailable

Watch0Fork0Star0
CodeCommitsIssuesPull requestsActionsInsightsSecurity
0d4452b33c2409d03315019dae0d34e468641dfb

Branches

Tags

  • No tags available.
0Branches0Tags
Go to file
Add file
Code

Clone

HTTPS

Download ZIP

hve-core/docs/customization

docs/customization/environment.md

334lines · modecode

RawDownload
Latest commit unavailable.
1---
2title: Environment Customization
3description: Configure DevContainers, VS Code settings, MCP servers, and coding agent environments for your team
4author: Microsoft
5ms.date: 2026-02-24
6ms.topic: how-to
7keywords:
8 - devcontainer
9 - vs code settings
10 - mcp servers
11 - environment
12estimated_reading_time: 6
13---
14
15## DevContainer Configuration
16
17HVE Core uses an Ubuntu 22.04 (Jammy) base image with Node.js 20, Python 3.11,
18and PowerShell 7 pre-installed. The configuration lives in
19`.devcontainer/devcontainer.json` and includes extensions for Markdown editing,
20spell checking, and GitHub integration.
21
22### Default Tool Stack
23
24The 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
37To 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
54Add new features by referencing published DevContainer features from the
55[DevContainers feature registry](https://containers.dev/features). For example,
56to 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
70Include team-specific extensions in the `customizations.vscode.extensions`
71array. 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
89Three 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
97Add custom setup steps to these scripts or create new scripts referenced from
98`devcontainer.json`.
99
100## VS Code Settings
101
102Workspace-level settings in `.vscode/settings.json` configure editor behavior,
103Copilot customization discovery, and validation tools. These settings apply to
104everyone who opens the workspace.
105
106### Key Settings
107
108The 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
122VS Code discovers customization files through `chat.*FilesLocations` settings.
123Each 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 }
143}
144```
145
146When you add a new collection directory, register it in these settings so Copilot
147discovers your customizations.
148
149### YAML Schema Validation
150
151The workspace maps YAML schemas to frontmatter validation:
152
153```json
154{
155 "yaml.schemas": {
156 "./scripts/linting/schemas/docs-frontmatter.schema.json": [
157 "docs/**/*.md"
158 ]
159 }
160}
161```
162
163This setup provides in-editor validation for frontmatter fields when the Red Hat
164YAML extension (`redhat.vscode-yaml`) is installed.
165
166### Commit Message Instructions
167
168Copilot uses a dedicated instructions file for generating commit messages:
169
170```json
171{
172 "github.copilot.chat.commitMessageGeneration.instructions": [
173 {
174 "file": ".github/instructions/hve-core/commit-message.instructions.md"
175 }
176 ]
177}
178```
179
180You can add your own commit message instructions file or replace this reference
181to match your team's commit conventions.
182
183## MCP Server Integration
184
185Model Context Protocol (MCP) servers extend Copilot's capabilities by connecting
186it to external tools and data sources. MCP servers run alongside VS Code and
187provide additional context, actions, or integrations that Copilot can invoke
188during conversations.
189
190### Configuration
191
192MCP servers are configured in `.vscode/mcp.json` at the workspace level:
193
194```json
195{
196 "servers": {
197 "github": {
198 "type": "http",
199 "url": "https://api.githubcopilot.com/mcp/"
200 }
201 }
202}
203```
204
205### Adding Team-Specific MCP Servers
206
207To integrate your team's tools, add server entries to the `servers` object.
208Each server needs a unique key, a type, and connection details:
209
210```json
211{
212 "servers": {
213 "github": {
214 "type": "http",
215 "url": "https://api.githubcopilot.com/mcp/"
216 },
217 "contoso-api": {
218 "type": "http",
219 "url": "https://mcp.contoso.com/v1/"
220 }
221 }
222}
223```
224
225MCP servers enable agents to interact with issue trackers, CI/CD pipelines,
226databases, and other systems your team relies on.
227
228## Coding Agent Environment
229
230The GitHub Copilot coding agent runs in a cloud-based GitHub Actions environment,
231separate from the local DevContainer. The
232`.github/workflows/copilot-setup-steps.yml` workflow pre-installs tools before
233the agent begins work.
234
235### Pre-Installed Tools
236
237The coding agent environment includes:
238
239* Node.js 20 with npm dependencies from `package.json`
240* Python 3.11
241* PowerShell 7 with PSScriptAnalyzer, PowerShell-Yaml, and Pester 5.7.1
242* shellcheck (pre-installed on ubuntu-latest)
243* actionlint for GitHub Actions workflow validation
244
245### Adding Tools for the Coding Agent
246
247Add installation steps to `copilot-setup-steps.yml`. Each tool should include
248SHA-verified downloads for security:
249
250```yaml
251- name: Install custom tool
252 env:
253 TOOL_VERSION: '1.0.0'
254 TOOL_SHA256: 'abc123...'
255 run: |
256 curl -sLO "https://example.com/tool_${TOOL_VERSION}.tar.gz"
257 echo "${TOOL_SHA256} tool_${TOOL_VERSION}.tar.gz" | sha256sum -c -
258 tar -xzf "tool_${TOOL_VERSION}.tar.gz" tool
259 sudo install tool /usr/local/bin/tool
260```
261
262### Validation
263
264The workflow supports manual execution through `workflow_dispatch`, allowing you
265to test setup changes before the coding agent encounters them.
266
267## Environment Synchronization
268
269The DevContainer (`on-create.sh`) and coding agent (`copilot-setup-steps.yml`)
270share most tools but differ intentionally in a few areas.
271
272### Shared Tools
273
274| Tool | DevContainer | Coding Agent |
275|------------------|--------------|--------------|
276| Node.js 20 | Yes | Yes |
277| Python 3.11 | Yes | Yes |
278| PowerShell 7 | Yes | Yes |
279| PSScriptAnalyzer | Yes | Yes |
280| Pester 5.7.1 | Yes | Yes |
281| shellcheck | Yes | Yes |
282| actionlint | Yes | Yes |
283
284### Intentional Differences
285
286| Tool | DevContainer | Coding Agent | Reason |
287|----------|--------------|--------------|------------------------------------------------|
288| gitleaks | Yes | No | Secret scanning is relevant for local dev only |
289
290### Keeping Environments Aligned
291
292When adding or removing tools in either environment, evaluate whether both need
293the change and update accordingly. Follow this checklist:
294
2951. Determine if the tool is needed for local development, coding agent work,
296 or both.
2972. Update `.devcontainer/scripts/on-create.sh` for DevContainer changes.
2983. Update `.github/workflows/copilot-setup-steps.yml` for coding agent changes.
2994. Pin dependency versions and verify checksums in both locations.
3005. Test the DevContainer rebuild and run the setup workflow via
301 `workflow_dispatch`.
302
303## Role Scenarios
304
305### SRE/Operations
306
307An SRE team at Fabrikam needs Terraform and kubectl available in both
308environments for infrastructure-as-code workflows.
309
310Steps to customize:
311
3121. Add the Terraform DevContainer feature to `devcontainer.json`
3132. Add a kubectl installation step to `on-create.sh`
3143. Mirror both installations in `copilot-setup-steps.yml`
3154. Add the Terraform VS Code extension to the DevContainer extensions list
3165. Register any IaC-specific instruction paths in `.vscode/settings.json`
317
318### Engineer
319
320A development team at Northwind Traders uses a custom API testing tool and wants
321Copilot to reference their internal MCP server during code reviews.
322
323Steps to customize:
324
3251. Add the API testing tool to `on-create.sh` and `copilot-setup-steps.yml`
3262. Configure the internal MCP server in `.vscode/mcp.json`
3273. Add workspace settings for any new extensions the team requires
3284. Create an instructions file that teaches Copilot about the team's API
329 conventions
330
331<!-- markdownlint-disable MD036 -->
332*🤖 Crafted with precision by ✨Copilot following brilliant human instruction,
333then carefully refined by our team of discerning human reviewers.*
334<!-- markdownlint-enable MD036 -->
335