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
, e.g:
├── src
│ ├── kubelogin
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
| ├── ...
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
...
An implementing tool will composite the documented dev container properties from the feature's devcontainer-feature.json
file, and execute in the install.sh
entrypoint script in the container during build time. Implementing tools are also free to process attributes under the customizations
property as desired.
All available options for a Feature are declared in the devcontainer-feature.json
. The syntax for the options
property can be found in the devcontainer Feature json properties reference.
Options are exported as Feature-scoped environment variables. The option name is captialized and sanitized according to option resolution.
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.
NOTE: The Distribution spec can be found here.
While any registry implementing 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 a GitHub Action workflow that will publish each Feature to GHCR.
Allow GitHub Actions to create and approve pull requests is 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
).
Each Feature is prefixed with the agilepathway/features
namespace. For example, the kubelogin
feature in this repository can be referenced in a devcontainer.json
with:
ghcr.io/agilepathway/features/kubelogin:1
The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: ghcr.io/agilepathway/features
. This contains information useful for tools aiding in Feature discovery.
'agilepathway/features
' is known as the feature collection namespace.
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/agilepathway/packages/container/features%2F<featureName>/settings
The Features in this collection are not currently published in the public index so that other community members can find them. This is because we want to wait a while until the features have proven themselves stable.
If we do decide at a later date to publish the features in the public index, this is what we need to do:
- 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.