[finalization] dev container feature distribution specification #70
Labels
finalization
Proposal to be made part of the spec
Comments
6 tasks
|
Whaou! I love ❤️ this new file organization. I was able to create and test my own features quickly. |
7 tasks
|
Features are now available broadly and in use so closing this issue out. Feel free to raise additional proposals in this repository. |
|
Once again me you guys 😀 |
hankei6km
added a commit
to hankei6km/h6-devcontainers-features
that referenced
this issue
Dec 16, 2023
# diff --git a/README.md b/README.md # index 1a1cea8..a8c294a 100644 # --- a/README.md # +++ b/README.md # @@ -1,188 +1,3 @@ # -# Dev Container Features: Self Authoring Template # +# h6-devcontainers-features # # -> This repo provides a starting point and example for creating your own custom [dev container Features](https://containers.dev/implementors/features/), hosted for free on GitHub Container Registry. The example in this repository follows the [dev container Feature distribution specification](https://containers.dev/implementors/features-distribution/). # -> # -> To provide feedback to the specification, please leave a comment [on spec issue #70](devcontainers/spec#70). For more broad feedback regarding dev container Features, please see [spec issue #61](devcontainers/spec#61). # - # -## Example Contents # - # -This repository contains a _collection_ of two Features - `hello` and `color`. These Features serve as simple feature implementations. Each sub-section below shows a sample `devcontainer.json` alongside example usage of the Feature. # - # -### `hello` # - # -Running `hello` inside the built container will print the greeting provided to it via its `greeting` option. # - # -```jsonc # -{ # - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", # - "features": { # - "ghcr.io/devcontainers/feature-starter/hello:1": { # - "greeting": "Hello" # - } # - } # -} # -``` # - # -```bash # -$ hello # - # -Hello, user. # -``` # - # -### `color` # - # -Running `color` inside the built container will print your favorite color to standard out. # - # -```jsonc # -{ # - "image": "mcr.microsoft.com/devcontainers/base:ubuntu", # - "features": { # - "ghcr.io/devcontainers/feature-starter/color:1": { # - "favorite": "green" # - } # - } # -} # -``` # - # -```bash # -$ color # - # -my favorite color is green # -``` # - # -## Repo and Feature Structure # - # -Similar to the [`devcontainers/features`](https://github.com/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 # -│ ├── hello # -│ │ ├── devcontainer-feature.json # -│ │ └── install.sh # -│ ├── color # -│ │ ├── devcontainer-feature.json # -│ │ └── install.sh # -| ├── ... # -│ │ ├── devcontainer-feature.json # -│ │ └── install.sh # -... # -``` # - # -An [implementing tool](https://containers.dev/supporting#tools) will composite [the documented dev container properties](https://containers.dev/implementors/features/#devcontainer-feature-json-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. # - # -### Options # - # -All available options for a Feature should be declared in the `devcontainer-feature.json`. The syntax for the `options` property can be found in the [devcontainer Feature json properties reference](https://containers.dev/implementors/features/#devcontainer-feature-json-properties). # - # -For example, the `color` feature provides an enum of three possible options (`red`, `gold`, `green`). If no option is provided in a user's `devcontainer.json`, the value is set to "red". # - # -```jsonc # -{ # - // ... # - "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 to [option resolution](https://containers.dev/implementors/features/#option-resolution). # - # -```bash # -#!/bin/bash # - # -echo "Activating feature 'color'" # -echo "The provided favorite color is: ${FAVORITE}" # - # -... # -``` # - # -## 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](https://containers.dev/implementors/features/#versioning). # - # -### Publishing # - # -> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/). # -> # -> While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/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](.github/workflows/release.yaml) 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 two Features in this repository can be referenced in a `devcontainer.json` with: # - # -``` # -ghcr.io/devcontainers/feature-starter/color:1 # -ghcr.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. # - # -### 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 # -``` # - # -<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png"> # - # -### Adding Features to the Index # - # -If you'd like your Features to appear in our [public index](https://containers.dev/features) so that other community members can find them, you can do the following: # - # -* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io) # - * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site # -* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file # - # -This index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/features/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. # - # -```jsonc # -{ # - "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" # - } # - } # - } # - } # - } # -} # -``` # +Features for Dev Containers. # Recent History # * 85e84fd (HEAD, origin/main, origin/HEAD, main) Merge pull request #2 from hankei6km:topic/shellcheck # |\ # | * 7850264 chore: Add "shellcheck" to devcontainer # |/ # * b0690ff Merge pull request #1 from hankei6km:topic/setup # |\ # | * 3917ebd chore: Add "codespaces" to "customizations" # | * e14e3e9 chore: Add scope-label workflow # | * 408add7 ci: Add sem-pr-label workflow # | * cd9e002 chore: Add init-labels.sh # | * 90301df chore: Update "features" in devcontainer.json # | * 9417cab style: Formatting "devcontainer.json" with prettier # |/ # * f6d0aaf Initial commit
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
and others
A forum to discuss the dev container feature distribution specification.
A continuation of the discussion found here: #7
The text was updated successfully, but these errors were encountered: