generated from devcontainers/feature-starter
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
41 changed files
with
533 additions
and
638 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,188 +1,57 @@ | ||
| # Dev Container Features: Self Authoring Template | ||
|
|
||
| > 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](https://github.com/devcontainers/spec/issues/70). For more broad feedback regarding dev container Features, please see [spec issue #61](https://github.com/devcontainers/spec/issues/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. | ||
| # Dev Container Features | ||
|
|
||
| ### `hello` | ||
| This repository contains a collection of features that can be used to enhance the development experience in a [Visual Studio Code Dev Container](https://code.visualstudio.com/docs/remote/containers). The features are organized in separate folders and can be used individually. | ||
|
|
||
| Running `hello` inside the built container will print the greeting provided to it via its `greeting` option. | ||
| ## Features Overview | ||
|
|
||
| ```jsonc | ||
| { | ||
| "image": "mcr.microsoft.com/devcontainers/base:ubuntu", | ||
| "features": { | ||
| "ghcr.io/devcontainers/feature-starter/hello:1": { | ||
| "greeting": "Hello" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| ### GitVersion | ||
|
|
||
| ```bash | ||
| $ hello | ||
| The [GitVersion](./src/gitversion/) feature installs GitVersion in the dev container. GitVersion is a tool that calculates a version number based on the Git history. The version number is written to a file that can be used in the build process. | ||
|
|
||
| Hello, user. | ||
| ``` | ||
| Originally, GitVersion was designed to be used in a CI/CD pipeline. However, it can also be used in a dev container to calculate the version number of the application. | ||
|
|
||
| ### `color` | ||
| More information about GitVersion can be found on the [GitVersion GitHub page](https://github.com/GitTools/GitVersion). | ||
|
|
||
| Running `color` inside the built container will print your favorite color to standard out. | ||
| ### GitUtils | ||
|
|
||
| ```jsonc | ||
| { | ||
| "image": "mcr.microsoft.com/devcontainers/base:ubuntu", | ||
| "features": { | ||
| "ghcr.io/devcontainers/feature-starter/color:1": { | ||
| "favorite": "green" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| The [GitUtils](./src/gitutils/) feature installs a collection of Git utilities in the dev container. The utilities are useful for automating Git workflows. | ||
|
|
||
| ```bash | ||
| $ color | ||
| The following utilities are included: [./src/gitutils/alias.json](./src/gitutils/alias.json) | ||
|
|
||
| my favorite color is green | ||
| ``` | ||
| #### Interactive Utilities | ||
|
|
||
| ## Repo and Feature Structure | ||
| - `git fixup` - Amend the specified commit with current changes and rebase | ||
|
|
||
| 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`. | ||
| #### GitFlow | ||
|
|
||
| ``` | ||
| ├── src | ||
| │ ├── hello | ||
| │ │ ├── devcontainer-feature.json | ||
| │ │ └── install.sh | ||
| │ ├── color | ||
| │ │ ├── devcontainer-feature.json | ||
| │ │ └── install.sh | ||
| | ├── ... | ||
| │ │ ├── devcontainer-feature.json | ||
| │ │ └── install.sh | ||
| ... | ||
| ``` | ||
| Additionnaly, the feature installs the [git-flow](https:://github.com/nvie/gitflow) extension and sets up the Git configuration to use it. | ||
|
|
||
| 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. | ||
| Shortcuts are also added to the `git` command to make it easier to use the `git-flow` commands: | ||
|
|
||
| ### Options | ||
| - `git beta` is a shortcut for `git flow release start` | ||
| - `git hfix` is a shortcut for `git flow hotfix start` | ||
| - `git prod` is a shortcut for `git flow release finish` and `git flow hotfix finish` | ||
|
|
||
| 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). | ||
| Those shortcuts work in cunjunction with the `gitversion` utility to automatically update the version number of the application. | ||
|
|
||
| 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". | ||
| ### Act | ||
|
|
||
| ```jsonc | ||
| { | ||
| // ... | ||
| "options": { | ||
| "favorite": { | ||
| "type": "string", | ||
| "enum": [ | ||
| "red", | ||
| "gold", | ||
| "green" | ||
| ], | ||
| "default": "red", | ||
| "description": "Choose your favorite color." | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| The [Act](./src/act/) feature installs the [nektos/act] tool in the dev container. Act is a tool that allows you to run GitHub Actions locally. | ||
|
|
||
| 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). | ||
| Originally, Act was designed to be used in a CI/CD pipeline. However, it can also be used in a dev container to test GitHub Actions locally. | ||
|
|
||
| ```bash | ||
| #!/bin/bash | ||
| More information about Act can be found on the [Act GitHub page](https://github.com/nektos/act). | ||
|
|
||
| echo "Activating feature 'color'" | ||
| echo "The provided favorite color is: ${FAVORITE}" | ||
| ### PECL | ||
|
|
||
| ... | ||
| ``` | ||
| The [PECL](./src/pecl/) feature installs the PHP Extension Community Library (PECL) in the dev container. PECL is a repository for PHP extensions. | ||
|
|
||
| ## Distributing Features | ||
| More information about PECL can be found on the [PECL website](https://pecl.php.net/). | ||
|
|
||
| ### Versioning | ||
| ## Contributing | ||
|
|
||
| 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). | ||
| If you have a feature that you would like to add to this repository, please open an issue or submit a pull request. | ||
|
|
||
| ### Publishing | ||
| ## License | ||
|
|
||
| > 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" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
| This repository is licensed under the [MIT License](./LICENSE). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
|
|
||
| # Nektos/Act | ||
|
|
||
| This feature provides a tool for running GitHub Actions locally | ||
|
|
||
| ## Example Usage | ||
|
|
||
| ```json | ||
| "features": { | ||
| "ghcr.io/tomgrv/devcontainer-features/act:1": { | ||
| "version": "latest" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Options | ||
|
|
||
| | Options Id | Description | Type | Default Value | | ||
| |-----|-----|-----|-----| | ||
| | version | The version of GitUtils to install. | string | latest | | ||
|
|
||
| ## Contributing | ||
|
|
||
| If you have a feature that you would like to add to this repository, please open an issue or submit a pull request. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| { | ||
| "name": "Nektos Act", | ||
| "id": "act", | ||
| "version": "1.0.4", | ||
| "description": "A tool for running GitHub Actions locally", | ||
| "installsAfter": [ | ||
| "ghcr.io/devcontainers/features/common-utils" | ||
| ], | ||
| "options": { | ||
| "version": { | ||
| "type": "string", | ||
| "description": "The version of act to install", | ||
| "default": "master" | ||
| } | ||
| }, | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| #!/bin/sh | ||
| set -e | ||
|
|
||
| echo "Activating feature 'nektos/act'" | ||
|
|
||
| ### Install Act | ||
| curl --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/nektos/act/${VERSION}/install.sh | sudo bash -s -- -b /usr/local/bin |
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.