Repository files navigation

This repo provides a starting point and example for creating your own customdev container Features, hosted for free on GitHub Container Registry. The example in this repository follows thedev container Feature distribution specification.

To provide feedback to the specification, please leave a commenton spec issue #70. For more broad feedback regarding dev container Features, please seespec issue #61.

This repository contains acollection of two Features -hello andcolor. These Features serve as simple feature implementations. Each sub-section below shows a sampledevcontainer.json alongside example usage of the Feature.

Runninghello inside the built container will print the greeting provided to it via itsgreeting option.

{"image":"mcr.microsoft.com/devcontainers/base:ubuntu","features": {"ghcr.io/devcontainers/feature-starter/hello:1": {"greeting":"Hello"        }    }}

$ helloHello, user.

Runningcolor inside the built container will print your favorite color to standard out.

{"image":"mcr.microsoft.com/devcontainers/base:ubuntu","features": {"ghcr.io/devcontainers/feature-starter/color:1": {"favorite":"green"        }    }}

$ colormy favorite color is green

Similar to thedevcontainers/features repo, this repository has asrc folder. Each Feature has its own sub-folder, containing at least adevcontainer-feature.json and an entrypoint scriptinstall.sh.

├── src│   ├── hello│   │   ├── devcontainer-feature.json│   │   └── install.sh│   ├── color│   │   ├── devcontainer-feature.json│   │   └── install.sh|   ├── ...│   │   ├── devcontainer-feature.json│   │   └── install.sh...

Animplementing tool will compositethe documented dev container properties from the feature'sdevcontainer-feature.json file, and execute in theinstall.sh entrypoint script in the container during build time. Implementing tools are also free to process attributes under thecustomizations property as desired.

All available options for a Feature should be declared in thedevcontainer-feature.json. The syntax for theoptions property can be found in thedevcontainer Feature json properties reference.

For example, thecolor feature provides an enum of three possible options (red,gold,green). If no option is provided in a user'sdevcontainer.json, the value is set to "red".

{// ..."options": {"favorite": {"type":"string","enum": ["red","gold","green"            ],"default":"red","description":"Choose your favorite color."        }    }}

Options are exported as Feature-scoped environment variables. The option name is captialized and sanitized according tooption resolution.

#!/bin/bashecho"Activating feature 'color'"echo"The provided favorite color is:${FAVORITE}"...

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

NOTE: The Distribution spec can befound here.

While any registryimplementing the OCI Distribution spec can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.

Features are meant to be easily sharable units of dev container configuration and installation code.

This repo contains aGitHub Actionworkflow that will publish each Feature to GHCR.

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

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

ghcr.io/devcontainers/feature-starter/color:1ghcr.io/devcontainers/feature-starter/hello:1

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

'devcontainers/feature-starter' is known as the feature collection namespace.

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

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

If you'd like your Features to appear in ourpublic index so that other community members can find them, you can do the following:

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

This index is from wheresupporting tools likeVS Code Dev Containers andGitHub Codespaces surface Features for their dev container creation UI.

For any Features hosted in GHCR that are kept private, theGITHUB_TOKEN access token in your environment will need to havepackage:read andcontents: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 indevcontainer.json

An exampledevcontainer.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"                    }                }            }        }    }}