Repository files navigation

This repo provides a starting point and example for creating your own customDev Container Templates, hosted for free on GitHub Container Registry. The example in this repository follows theDev Container Template distribution specification.

To provide feedback on the distribution spec, please leave a commenton spec issue #71.

This repository contains acollection of two Templates -hello andcolor. These Templates serve as simple template implementations which helps containerize the project. Similar to thedevcontainers/templates repo, this repository has asrc folder. Each Template has its own sub-folder, containing at least adevcontainer-template.json and.devcontainer/devcontainer.json.

├── src│   ├── color│   │   ├── devcontainer-template.json│   │   └──| .devcontainer│   │      └── devcontainer.json│   ├── hello│   │   ├── devcontainer-template.json│   │   └──| .devcontainer│   │      ├── devcontainer.json│   │      └── Dockerfile|   ├── ...│   │   ├── devcontainer-template.json│   │   └──| .devcontainer│   │      └── devcontainer.json├── test│   ├── color│   │   └── test.sh│   ├── hello│   │   └── test.sh│   └──test-utils│      └── test-utils.sh...

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

For example, thecolor Template provides three possible options (red,gold,green), where the default value is set to "red".

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

Animplementing tool will use theoptions property fromthe documented Dev Container Template properties for customizing the Template. Seeoption resolution example for details.

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

Templates are individually versioned by theversion attribute in a Template'sdevcontainer-template.json. Templates are versioned according to the semver specification. More details can be found inthe Dev Container Template 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.

Templates are source files packaged together that encode configuration for a complete development environment.

This repo contains a GitHub Actionworkflow that will publish each template to GHCR. By default, each Template will be prefixed with the<owner>/<repo> namespace. For example, the two Templates in this repository can be referenced by animplementing tool with:

ghcr.io/devcontainers/template-starter/color:latestghcr.io/devcontainers/template-starter/hello:latest

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

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

For your Template to be used, it currently needs to be available publicly. By default, OCI Artifacts in GHCR are marked asprivate.

To make them public, navigate to the Template's "package settings" page in GHCR, and set the visibility to 'public`.

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

Next you will need to add your Templates collection to ourpublic index so that other community members can find them. Just follow these steps once per collection you create:

• 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 Templates for their Dev Container Creation Configuration UI.

This repo contains a GitHub Actionworkflow for testing the Templates. Similar to thedevcontainers/templates repo, this repository has atest folder. Each Template has its own sub-folder, containing at least atest.sh.

For running the tests locally, you would need to execute the following commands -

    ./.github/actions/smoke-test/build.sh ${TEMPLATE-ID}     ./.github/actions/smoke-test/test.sh ${TEMPLATE-ID}

This repo contains a GitHub Actionworkflow that will automatically generate documentation (ie.README.md) for each Template. This file will be auto-generated from thedevcontainer-template.json andNOTES.md.