Skip to content

Document "dev" tagged images #1787

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 5 commits into
base: main
Choose a base branch
from
+47 −1
Open

Document "dev" tagged images #1787

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
1f5e021
Initial plan
Copilot Feb 18, 2026
5b4dbaa
Document purpose and usage of "dev" tagged images
Copilot Feb 18, 2026
94184bd
Apply suggestion from @Copilot
abdurriq Feb 19, 2026
54fb94d
Apply suggestion from @Copilot
abdurriq Feb 19, 2026
e6260c4
Merge branch 'main' into copilot/document-dev-python-images
Kaniska244 Feb 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion build/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,52 @@ This CLI is used in the GitHub Actions workflows in this repository.
- `smoke-*.yaml` (using the `smoke-test` action in this repository) - Runs a build without pushing and executes `test-project/test.sh` (if present) inside the container to verify that there are no breaking changes to the image when the repository contents are updated.
- `version-history.yml`: Listens for workflow dispatch events to trigger cgmanifest.json and history markdown generation.

## "dev" tagged images

In addition to versioned releases, this repository publishes special "dev" tagged image variants. Understanding their purpose and characteristics helps you choose the right image for your needs.

### Purpose

"dev" images are preview builds generated from the main branch. They provide early access to:
- Upstream OS package updates
- New language runtime versions
- Repository improvements before official releases

### Tagging pattern

Images receive both generic and specific dev tags:
- Generic: `mcr.microsoft.com/devcontainers/<image>:dev`
- With version: `mcr.microsoft.com/devcontainers/<image>:dev-<version>`
- With distro: `mcr.microsoft.com/devcontainers/<image>:dev-<distro>`
- Combined: `mcr.microsoft.com/devcontainers/<image>:dev-<version>-<distro>`

Comment on lines +35 to +40
Copy link

Copilot AI Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The placeholders in the “Tagging pattern” section are a bit ambiguous about what <version> and <distro> represent. In this repo, dev tags are generated by substituting ${VERSION} with dev in each image’s tag templates (see src/*/manifest.json), so the “version” portion is often the runtime variant (e.g., 3.13) and the “distro” is the OS codename (e.g., trixie/bookworm). Consider clarifying this (or adding one concrete example like python:dev-3.13 and python:dev-3.13-trixie) to prevent confusion with the image’s semantic version (e.g., 3.0.5).

Suggested change
Images receive both generic and specific dev tags:
- Generic: `mcr.microsoft.com/devcontainers/<image>:dev`
- With version: `mcr.microsoft.com/devcontainers/<image>:dev-<version>`
- With distro: `mcr.microsoft.com/devcontainers/<image>:dev-<distro>`
- Combined: `mcr.microsoft.com/devcontainers/<image>:dev-<version>-<distro>`
Images receive both generic and specific dev tags. In this context, `<version>` is typically the runtime or language variant (for example, `3.13`), and `<distro>` is the OS codename (for example, `trixie` or `bookworm`):
- Generic: `mcr.microsoft.com/devcontainers/<image>:dev`
- With version: `mcr.microsoft.com/devcontainers/<image>:dev-<version>`
- With distro: `mcr.microsoft.com/devcontainers/<image>:dev-<distro>`
- Combined: `mcr.microsoft.com/devcontainers/<image>:dev-<version>-<distro>`
For example, the Python image might be tagged as `mcr.microsoft.com/devcontainers/python:dev-3.13` and `mcr.microsoft.com/devcontainers/python:dev-3.13-trixie`.

Copilot uses AI. Check for mistakes.
### Update frequency

Weekly automated builds occur every Monday via `push-dev.yml` workflow, ensuring dev images stay current with main branch changes.

### Usage recommendations

**Use dev images for:**
- Testing unreleased features
- Validating upcoming changes
- Development environments where latest updates are desired

**Avoid dev images for:**
- Production workloads
- Reproducible CI/CD pipelines
- Stable development environments

**Migration example:**
```dockerfile
# Preview/testing
FROM mcr.microsoft.com/devcontainers/python:dev-3.13

# Stable/production
FROM mcr.microsoft.com/devcontainers/python:3-3.13
```

The versioned tag provides stability while dev tags continuously incorporate changes.

## Setting up a container to be built

> **Note:** Only @devcontainers/maintainers can currently onboard an image to this process since it requires access the Microsoft Container Registry. [See here for details](https://github.com/microsoft/vscode-internalbacklog/wiki/Remote-Container-Images-MCR-Setup).
Expand Down Expand Up @@ -148,7 +194,7 @@ In this case, Debian is also the one that is used for `latest` for the `base` re

> **NOTE:** The version number used for this repository should be kept in sync with the VS Code Remote - Containers extension to make it easy for developers to find.

There's a special "dev" version that can be used to build main on CI - I ended up needing this to test and others would if they base an image off of one of the MCR images. e.g. `dev-debian-11`.
In addition to versioned tags, "dev" tags are also generated for testing purposes. See the ["dev" tagged images](#dev-tagged-images) section for details on their purpose and usage.

### The `version` property

Expand Down
Loading