microsoft/hve-core

Public

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

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

83a260607c12fda28c813d44de416bad498156ff

Find a branch or tag

Branches

83a260607c12fda28c813d44de416bad498156ff

Clone

HTTPS

Download ZIP

hve-core/docs/customization

docs/customization/environment.md

347lines · modecode

Raw Download

Latest commit unavailable.

unknown

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

microsoft/hve-core

Branches

Tags

Clone