hve-core/docs/customization/environment.md at main · zeier/hve-core

title

Environment Customization

description

Configure DevContainers, VS Code settings, MCP servers, and coding agent environments for your team

author

Microsoft

ms.date

2026-08-12

ms.topic

how-to

keywords

devcontainer

vs code settings

mcp servers

environment

estimated_reading_time

DevContainer Configuration

HVE Core uses an Ubuntu 22.04 (Jammy) base image with Node.js 24, Python 3.11, and PowerShell 7.4 pre-installed. The configuration lives in .devcontainer/devcontainer.json and includes extensions for Markdown editing, spell checking, and GitHub integration.

Default Tool Stack

The DevContainer ships with these tools:

Node.js 24 with npm
Python 3.11
PowerShell 7.4 with PSScriptAnalyzer 1.25.0, PowerShell-Yaml 0.4.7, and Pester 5.7.1
Git and GitHub CLI
GitHub Copilot CLI (copilot)
Azure CLI
shellcheck for bash validation
actionlint for GitHub Actions workflow validation
cosign for artifact signing and verification
gitleaks for secret scanning

Customizing for Your Team

To add tools or adjust versions, modify .devcontainer/devcontainer.json. The features section controls language runtimes and CLIs:

{
  "features": {
    "ghcr.io/devcontainers/features/node:1": {
      "version": "24"
    },
    "ghcr.io/devcontainers/features/python:1": {
      "version": "3.11"
    },
    "ghcr.io/devcontainers/features/powershell:1": {}
  }
}

Add new features by referencing published DevContainer features from the DevContainers feature registry. For example, to add Terraform:

{
  "features": {
    "ghcr.io/devcontainers/features/terraform:1": {
      "version": "1.6"
    }
  }
}

Lockfile

When the dev container builds, it generates a devcontainer-lock.json file in the same directory as devcontainer.json. This lockfile pins each feature to an exact version and OCI SHA-256 digest, providing reproducible builds and supply-chain integrity verification. The lockfile is committed to source control and validated by CI.

After modifying features in devcontainer.json, rebuild the dev container to regenerate devcontainer-lock.json and commit both files together. PR validation fails if the lockfile is missing or out of sync with devcontainer.json.

Adding VS Code Extensions

Include team-specific extensions in the customizations.vscode.extensions array. Each entry uses the publisher.extensionId format:

{
  "customizations": {
    "vscode": {
      "extensions": [
        "streetsidesoftware.code-spell-checker",
        "davidanson.vscode-markdownlint",
        "ms-python.python"
      ]
    }
  }
}

Lifecycle Scripts

Three lifecycle hooks execute during container setup:

onCreateCommand runs .devcontainer/scripts/on-create.sh to install system dependencies (shellcheck, actionlint, PowerShell modules, gitleaks)
updateContentCommand runs npm ci to install JavaScript dependencies
postCreateCommand runs .devcontainer/scripts/post-create.sh for final configuration

Add custom setup steps to these scripts or create new scripts referenced from devcontainer.json.

VS Code Settings

Workspace-level settings in .vscode/settings.json configure editor behavior, Copilot customization discovery, and validation tools. These settings apply to everyone who opens the workspace.

Key Settings

The workspace configures several critical behaviors:

{
  "editor.formatOnSave": true,
  "[markdown]": {
    "editor.defaultFormatter": "davidanson.vscode-markdownlint"
  },
  "search.followSymlinks": false
}

Copilot Discovery Paths

VS Code discovers customization files through chat.*FilesLocations settings. Each entry maps a directory path to true to enable scanning:

{
  "chat.instructionsFilesLocations": {
    ".github/instructions/hve-core": true,
    ".github/instructions/coding-standards": true
  },
  "chat.agentFilesLocations": {
    ".github/agents/hve-core": true,
    ".github/agents/hve-core/subagents": true
  },
  "chat.promptFilesLocations": {
    ".github/prompts/hve-core": true
  },
  "chat.agentSkillsLocations": {
    ".github/skills": true,
    ".github/skills/shared": true,
    ".github/skills/coding-standards": true,
    ".github/skills/design-thinking": true
  }
}

When you add a new collection directory, register it in these settings so Copilot discovers your customizations.

YAML Schema Validation

The workspace maps YAML schemas to frontmatter validation:

{
  "yaml.schemas": {
    "./scripts/linting/schemas/docs-frontmatter.schema.json": [
      "docs/**/*.md"
    ]
  }
}

This setup provides in-editor validation for frontmatter fields when the Red Hat YAML extension (redhat.vscode-yaml) is installed.

Commit Message Instructions

Copilot uses a dedicated instructions file for generating commit messages:

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    {
      "file": ".github/instructions/hve-core/commit-message.instructions.md"
    }
  ]
}

You can add your own commit message instructions file or replace this reference to match your team's commit conventions.

MCP Server Integration

Model Context Protocol (MCP) servers extend Copilot's capabilities by connecting it to external tools and data sources. MCP servers run alongside VS Code and provide additional context, actions, or integrations that Copilot can invoke during conversations.

Configuration

MCP servers are configured in .vscode/mcp.json at the workspace level:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Adding Team-Specific MCP Servers

To integrate your team's tools, add server entries to the servers object. Each server needs a unique key, a type, and connection details:

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "contoso-api": {
      "type": "http",
      "url": "https://mcp.contoso.com/v1/"
    }
  }
}

MCP servers enable agents to interact with issue trackers, CI/CD pipelines, databases, and other systems your team relies on.

Coding Agent Environment

The GitHub Copilot coding agent runs in a cloud-based GitHub Actions environment, separate from the local DevContainer. The .github/workflows/copilot-setup-steps.yml workflow pre-installs tools before the agent begins work.

Pre-Installed Tools

The coding agent environment includes:

Node.js 24 with npm dependencies from package.json
Python 3.11
PowerShell 7.4 with PSScriptAnalyzer 1.25.0, PowerShell-Yaml 0.4.7, and Pester 5.7.1
shellcheck (pre-installed on ubuntu-latest)
actionlint for GitHub Actions workflow validation
cosign for artifact signing and verification
osv-scanner for dependency vulnerability scanning

Adding Tools for the Coding Agent

Add installation steps to copilot-setup-steps.yml. Each tool should include SHA-verified downloads for security:

- name: Install custom tool
  env:
    TOOL_VERSION: '1.0.0'
    TOOL_SHA256: 'abc123...'
  run: |
    curl -sLO "https://example.com/tool_${TOOL_VERSION}.tar.gz"
    echo "${TOOL_SHA256}  tool_${TOOL_VERSION}.tar.gz" | sha256sum -c -
    tar -xzf "tool_${TOOL_VERSION}.tar.gz" tool
    sudo install tool /usr/local/bin/tool

Validation

The workflow supports manual execution through workflow_dispatch, allowing you to test setup changes before the coding agent encounters them.

Environment Synchronization

The DevContainer (on-create.sh) and coding agent (copilot-setup-steps.yml) share most tools but differ intentionally in a few areas.

Shared Tools

Tool	DevContainer	Coding Agent
Node.js 24	Yes	Yes
Python 3.11	Yes	Yes
PowerShell 7.4	Yes	Yes
PSScriptAnalyzer 1.25.0	Yes	Yes
Pester 5.7.1	Yes	Yes
shellcheck	Yes	Yes
actionlint	Yes	Yes
cosign	Yes	Yes
osv-scanner	Yes	Yes

Intentional Differences

Tool	DevContainer	Coding Agent	Reason
gitleaks	Yes	No	Secret scanning is relevant for local dev only

Keeping Environments Aligned

When adding or removing tools in either environment, evaluate whether both need the change and update accordingly. Follow this checklist:

Determine if the tool is needed for local development, coding agent work, or both.
Update .devcontainer/scripts/on-create.sh for DevContainer changes.
Update .github/workflows/copilot-setup-steps.yml for coding agent changes.
Pin dependency versions and verify checksums in both locations.
Test the DevContainer rebuild and run the setup workflow via workflow_dispatch.

Role Scenarios

SRE/Operations

An SRE team at Fabrikam needs Terraform and kubectl available in both environments for infrastructure-as-code workflows.

Steps to customize:

Add the Terraform DevContainer feature to devcontainer.json
Add a kubectl installation step to on-create.sh
Mirror both installations in copilot-setup-steps.yml
Add the Terraform VS Code extension to the DevContainer extensions list
Register any IaC-specific instruction paths in .vscode/settings.json

Engineer

A development team at Northwind Traders uses a custom API testing tool and wants Copilot to reference their internal MCP server during code reviews.