Dev Container Features

This repository contains these features:

Table of all features:

Feature	Description
Zig	Zig from official releases or custom url, like Mach Engine

Usage

To reference a Feature from this repository, add the desired Features to a devcontainer.json. Each Feature has a README.md that shows how to reference the Feature and which options are available for that Feature.

The example below installs the zig declared in the ./src/zig directory of this repository.

See the relevant Feature's README for supported options.

"name": "my-project-devcontainer",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",  // Any generic, debian-based image.
"features": {
    "ghcr.io/hcanber/devcontainers_features/zig": {
    }
}

The :latest version annotation is added implicitly if omitted. To pin to a specific package version (example), append it to the end of the Feature. Features follow semantic versioning conventions, so you can pin to a major version :1, minor version :1.0, or patch version :1.0.0 by specifying the appropriate label.

"features": {
    "ghcr.io/devcontainers/features/zig:1.0.0": {
    }
}

---

Adding new Features to this repository

Open this repository in VSCode and opt-in to opening the workspace in a dev container. This will provide a consistent development environment for all Features.

Adding a new Feature

• Add a folder under src/ with the name of the Feature. The folder should contain at least a devcontainer-feature.json and an entrypoint script install.sh. Note that README.md files are updated automatically.

  [!TIP] Add a NOTES.md as it will be added to the end of the generated README.md

• Add a folder under test/ with the name of the Feature. The folder should contain at least a scenarios.json and a test script test.sh.

• Add the Feature to .github/workflows/test.yaml

• Add it to the Feature list at the top in this README.md

Note

The Feature's README.md is generated automatically.

Running tests

In VSCode open a terminal and execute:

devcontainer features test

To test a specific Feature, use the --feature / -f flag:

devcontainer features test -f zig

Optionally specify the base image to use using the --base-image / -i flag:

devcontainer features test -f zig -i mcr.microsoft.com/devcontainers/base:jammy

For more info see https://github.com/devcontainers/cli/blob/main/docs/features/test.md#dev-container-features-test-lib

Repo and Feature Structure

Similar to the devcontainers/features repo, this repository has a src folder. Each Feature has its own sub-folder, containing at least a devcontainer-feature.json and an entrypoint script install.sh.

├── src
│   ├── zig
│   │   ├── devcontainer-feature.json
│   │   └── install.sh
|   ├── ...
│   │   ├── devcontainer-feature.json
│   │   └── install.sh
├── test
│   ├── zig
│   │   ├── scenarios.json
│   │   └── test.sh
|   ├── ...
│   │   ├── scenarios.json
│   │   └── test.sh
...

Distributing Features

Versioning

Features are individually versioned by the version attribute in a Feature's devcontainer-feature.json. Features are versioned according to the semver specification. More details can be found in the dev container Feature specification.

Publishing

This repo contains a GitHub Action workflow that will publish each Feature to GHCR.

Allow GitHub Actions to create and approve pull requests should be enabled in the repository's Settings > Actions > General > Workflow permissions for auto generation of src/<feature>/README.md per Feature (which merges any existing src/<feature>/NOTES.md).

By default, each Feature will be prefixed with the <owner/<repo> namespace. For example, the Features in this repository can be referenced in a devcontainer.json with:

ghcr.io/<owner/<repo>/<featureName>:1

The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: ghcr.io/<owner/<repo>. This contains information useful for tools aiding in Feature discovery.

'<owner/<repo>' is known as the feature collection namespace.

Marking Feature Public

Note that by default, GHCR packages are marked as private. To stay within the free tier, Features need to be marked as public.

This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like:

https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings

Adding Features to the Index

For Features to appear in public index, so that other community members can find them, do the following:

• Go to github.com/devcontainers/devcontainers.github.io
  • This is the GitHub repo backing the containers.dev spec site
• Open a PR to modify the collection-index.yml file

This index is from where supporting tools like VS Code Dev Containers and GitHub Codespaces surface Features for their dev container creation UI.

Using private Features in Codespaces

For any Features hosted in GHCR that are kept private, the GITHUB_TOKEN access token in your environment will need to have package:read and contents:read for the associated repository.

Many implementing tools use a broadly scoped access token and will work automatically. GitHub Codespaces uses repo-scoped tokens, and therefore you'll need to add the permissions in devcontainer.json

An example devcontainer.json can be found below.

{
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "features": {
     "ghcr.io/my-org/private-features/hello:1": {
            "greeting": "Hello"
        }
    },
    "customizations": {
        "codespaces": {
            "repositories": {
                "my-org/private-features": {
                    "permissions": {
                        "packages": "read",
                        "contents": "read"
                    }
                }
            }
        }
    }
}