Adding and Configuring Dev Containers

What are dev containers and how can we configure them for GitHub Codespaces? This guide explains the purpose of dev containers and shows how to use a devcontainer.json file to define a consistent, fully featured development workspace. A dev container is a Docker container configured to provide a reproducible environment that includes the operating system, runtimes, tooling, VS Code extensions, and automated setup steps. In GitHub Codespaces, each session runs inside one of these containers on a high-performance VM. By defining your environment as code, every developer—regardless of their local setup—gets the exact same tools, runtimes, and editor settings. Here is a representative devcontainer.json (JSON with comments / JSONC) showing common configuration options:

{
  "name": "Full Stack Environment",
  // 1. Define the base image (the operating system and runtime)
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  // 2. Install VS Code extensions automatically for the team
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-azuretools.vscode-docker"
      ],
      "settings": {
        "editor.formatOnSave": true
      }
    }
  },
  // 3. Forward ports to allow browser access to the running app
  "forwardPorts": [3000, 8080],
  // 4. Run commands AFTER the container is created (e.g., install dependencies)
  "postCreateCommand": "npm install",
  // 5. Use 'features' to quickly add extra tools like the GitHub CLI
  "features": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  // 6. Set the user to 'vscode' rather than 'root' for security
  "remoteUser": "vscode"
}

Why this matters

Reproducibility: Everyone uses the same base image, runtime, and extensions.
Onboarding: New contributors can start coding without manual environment setup.
CI parity: You can match local development containers to CI images to reduce “works on my machine” issues.

Where to place this file

Place the devcontainer.json file in the repository root under .devcontainer/ (for example .devcontainer/devcontainer.json). Both GitHub Codespaces and VS Code Remote - Containers look here to build the workspace container.

Key fields in devcontainer.json

Property	Purpose	Example
`name`	Human-friendly name for the container	`"Full Stack Environment"`
`image` / `build`	Use a prebuilt image (`image`) or build from a `Dockerfile` (`build`)	`"image": "mcr.microsoft.com/devcontainers/javascript-node:20"`
`customizations.vscode.extensions`	Auto-install VS Code extensions for anyone who opens the container	`["dbaeumer.vscode-eslint"]`
`customizations.vscode.settings`	Workspace-specific VS Code settings	`"editor.formatOnSave": true`
`forwardPorts`	Ports to expose from the container for previews	`[3000, 8080]`
`postCreateCommand`	One-time setup commands that run after the container is created	`"npm install"`
`postStartCommand`	Commands that run every time the container starts	`"./scripts/start-services.sh"`
`postAttachCommand`	Commands that run after the editor attaches to the container	`"echo 'Welcome to the container!'"`
`features`	Quick install of common tools using Dev Container Features	`{"ghcr.io/devcontainers/features/github-cli:1":{}}`
`remoteUser`	Non-root user to use inside the container for interactive sessions	`"vscode"`

Lifecycle hooks and when to use them

Hook	When it runs	Typical use cases / examples
`postCreateCommand`	Once, after the container is created (first build)	Install dependencies (`npm install`, `pip install -r requirements.txt`), scaffold files
`postStartCommand`	Every container start	Start background processes, local services (`./scripts/start-dev-db.sh`)
`postAttachCommand`	After the editor attaches	Display a welcome message, open specific files, run interactive checks

Example: when to use postCreateCommand vs postStartCommand

Use postCreateCommand for one-time setup tasks that should only run when the container is first built (for example, npm install or generating boilerplate files).
Use postStartCommand for tasks that should run whenever the container starts (for example, starting a local database or a background watcher).

Do not store secrets (API keys, passwords) directly in devcontainer.json or committed scripts. Use environment variables provided by Codespaces, GitHub Actions secrets, or other secret-management tools to inject sensitive values at runtime.

Features, tooling, and extensions

Use the Dev Container Features registry to add common tooling quickly (GitHub CLI, Docker CLI, Python, Node.js, terraform, etc.).
Extensions listed under customizations.vscode.extensions will be automatically installed for anyone opening the container—this ensures team-wide consistency for linters, formatters, and language tooling.

Dev container configuration files are JSONC (JSON with comments). To keep the devcontainer.json concise and maintainable, put longer or sensitive setup logic into scripts in the repository (for example, scripts/setup.sh) and invoke them from postCreateCommand or other hooks.

Summary

A devcontainer.json makes your development environment portable and reproducible across machines and Codespaces.
Store it in .devcontainer/devcontainer.json and use it to define the base image or Dockerfile, editor customizations, forwarded ports, lifecycle hooks, and optional features.
In GitHub Codespaces, this file instructs Codespaces how to build each workspace container so every team member has the same environment.

Links and references

Watch Video

Demo Configure a Codespace

Demo How to Use the githubdev Editor

Introduction

Git and GitHub Basics

GitHub Entities

GitHub Markdown

GitHub Desktop

GitHub Mobile

GitHub Repositories

Issues

Pull Requests

Discussions

Notifications

Gists, Wikis, and GitHub Pages

GitHub Actions

GitHub Copilot

GitHub Codespaces

Manage Your Work with GitHub Projects

Authentication and Security

GitHub Administration

Benefits of Open-Source Community

Benefits of Open Source – Applications

Adding and Configuring Dev Containers

Watch Video