devcontainer

---
name: devcontainer
description: "Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'."
source: package
domain: devops
---

# devcontainer

## When to use

Use this skill when working with DevContainer configuration, GitHub Codespaces setup, or development environment standardization.

Do NOT use when:
- Local Docker setup without Codespaces (use `docker` skill)
- Production deployment (use `aws-infrastructure` skill)

## Procedure: Modify DevContainer

1. **Gather context** — read `.devcontainer/devcontainer.json`, check `.devcontainer/` for env files and docs, check `agents/overrides/skills/devcontainer.md` for project-specific overrides.
2. **Identify change type** — classify: image change, feature addition, secret addition, extension change, or env var change.
3. **Make the change** — edit `devcontainer.json` (or related files). Follow conventions below for secrets, features, and env variables.
4. **Build and verify** — run `devcontainer build` to confirm the container builds. Check that extensions load and ports forward correctly.
5. **Document** — if adding a new secret or dependency, update the onboarding docs in `.devcontainer/`.

## Architecture

### Custom image

DevContainers typically use a **pre-built custom image** hosted on a container registry (GHCR, ECR, Docker Hub). Read `devcontainer.json` for the image URL.

The image should include:
- Language runtime (PHP, Node.js, Python, etc.)
- Package managers (Composer, npm, etc.)
- Common development tools

### Features (installed on top of the image)

Common features:

| Feature | Purpose |
|---|---|
| `git` | Git version control |
| `github-cli` | GitHub CLI (`gh`) for API access |
| `docker-in-docker` | Run Docker inside the DevContainer |

### Secrets management

Secrets can be managed via:
- **File mounts**: `.devcontainer/.secrets/<NAME>` → `/run/secrets/<NAME>`
- **GitHub Codespaces secrets**: configured in the repository settings
- **Environment variables**: in `.devcontainer/devcontainer.env`

Read `devcontainer.json` for the actual secret definitions and requirements.

### Workspace

- **Workspace folder**: typically `/workspace` or `/workspaces/{repo-name}`
- **Mount type**: bind mount from local workspace
- Container name and hostname: defined in `devcontainer.json`

### IDE integration

- VS Code Live Share for collaborative development
- IDE extensions can be pre-configured in `devcontainer.json`

## Conventions

### Adding new secrets

1. Add the secret definition to `devcontainer.json` → `secrets` section.
2. Add a bind mount from `.devcontainer/.secrets/<NAME>` to `/run/secrets/<NAME>`.
3. Document the secret with `description` and `documentationUrl`.
4. Mark as required or optional.

### Modifying the base image

- If the base image is maintained in a separate repository, do NOT change the image tag without coordination.
- Prefer adding **features** over modifying the base image.

### Environment variables

- Runtime env vars go in `.devcontainer/devcontainer.env`.
- Secrets go in `.devcontainer/.secrets/` (gitignored).
- Do NOT hardcode secrets in `devcontainer.json`.

## Output format

1. Updated devcontainer.json or related configuration files
2. Summary of changes and rebuild requirements

## Auto-trigger keywords

- DevContainer
- Codespaces
- dev env
- container setup

### Validate

- Verify the DevContainer builds successfully (`devcontainer build`).
- Confirm all required extensions and features are installed.
- Check that port forwarding and volume mounts work as expected.

## Gotcha

- DevContainer rebuilds are slow — test configuration changes incrementally, not all at once.
- Secrets in devcontainer.json are visible in version control — use Codespaces secrets instead.
- Extensions in devcontainer.json install on EVERY rebuild — keep the list short.

## Do NOT

- Do NOT commit secret files — they should be gitignored.
- Do NOT change the workspace mount path without updating all related configs.
- Do NOT remove required secrets without checking which services depend on them.
- Do NOT switch base images without team approval.

## Related

- **Skill:** `docker` — Docker setup, multi-stage Dockerfile, compose services
- **Skill:** `traefik` — local reverse proxy with real domains and HTTPS
- **Rule:** `docker-commands.md` — commands run inside Docker