name: 'Smoke test'

inputs:

template:

description: 'Template to test'

required: true

runs:

using: composite

steps:

- name: Checkout main

id: checkout_release

uses: actions/checkout@v3

- name: Build template

id: build_template

shell: bash

run: ${{ github.action_path }}/build.sh ${{ inputs.template }}

- name: Test template

id: test_template

shell: bash

run: ${{ github.action_path }}/test.sh ${{ inputs.template }}

TEMPLATE_ID="$1"

set -e

shopt -s dotglob

SRC_DIR="/tmp/${TEMPLATE_ID}"

cp -R "src/${TEMPLATE_ID}" "${SRC_DIR}"

pushd "${SRC_DIR}"

OPTION_PROPERTY=( $(jq -r '.options' devcontainer-template.json) )

if [ "${OPTION_PROPERTY}" != "" ] && [ "${OPTION_PROPERTY}" != "null" ] ; then

OPTIONS=( $(jq -r '.options | keys[]' devcontainer-template.json) )

if [ "${OPTIONS[0]}" != "" ] && [ "${OPTIONS[0]}" != "null" ] ; then

echo "(!) Configuring template options for '${TEMPLATE_ID}'"

for OPTION in "${OPTIONS[@]}"

do

OPTION_KEY="\${templateOption:$OPTION}"

OPTION_VALUE=$(jq -r ".options | .${OPTION} | .default" devcontainer-template.json)

if [ "${OPTION_VALUE}" = "" ] || [ "${OPTION_VALUE}" = "null" ] ; then

echo "Template '${TEMPLATE_ID}' is missing a default value for option '${OPTION}'"

exit 1

fi

echo "(!) Replacing '${OPTION_KEY}' with '${OPTION_VALUE}'"

OPTION_VALUE_ESCAPED=$(sed -e 's/[]\/$*.^[]/\\&/g' <<<"${OPTION_VALUE}")

find ./ -type f -print0 | xargs -0 sed -i "s/${OPTION_KEY}/${OPTION_VALUE_ESCAPED}/g"

done

fi

TEST_DIR="test/${TEMPLATE_ID}"

if [ -d "${TEST_DIR}" ] ; then

echo "(*) Copying test folder"

DEST_DIR="${SRC_DIR}/test-project"

mkdir -p ${DEST_DIR}

cp -Rp ${TEST_DIR}/* ${DEST_DIR}

cp test/test-utils/test-utils.sh ${DEST_DIR}

export DOCKER_BUILDKIT=1

echo "(*) Installing @devcontainer/cli"

npm install -g @devcontainers/cli

echo "Building Dev Container"

ID_LABEL="test-container=${TEMPLATE_ID}"

devcontainer up --id-label ${ID_LABEL} --workspace-folder "${SRC_DIR}"

TEMPLATE_ID="$1"

set -e

SRC_DIR="/tmp/${TEMPLATE_ID}"

echo "Running Smoke Test"

ID_LABEL="test-container=${TEMPLATE_ID}"

devcontainer exec --workspace-folder "${SRC_DIR}" --id-label ${ID_LABEL} /bin/sh -c 'set -e && if [ -f "test-project/test.sh" ]; then cd test-project && if [ "$(id -u)" = "0" ]; then chmod +x test.sh; else sudo chmod +x test.sh; fi && ./test.sh; else ls -a; fi'

docker rm -f $(docker container ls -f "label=${ID_LABEL}" -q)

rm -rf "${SRC_DIR}"

name: "Release Dev Container Templates & Generate Documentation"

on:

workflow_dispatch:

jobs:

deploy:

if: ${{ github.ref == 'refs/heads/main' }}

runs-on: ubuntu-latest

permissions:

packages: write

contents: write

pull-requests: write

steps:

- uses: actions/checkout@v3

- name: "Publish Templates"

uses: devcontainers/action@v1

with:

publish-templates: "true"

base-path-to-templates: "./src"

generate-docs: "true"

env:

GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Create PR for Documentation

id: push_image_info

env:

GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

run: |

name: "CI - Test Templates"

on:

pull_request:

jobs:

detect-changes:

runs-on: ubuntu-latest

outputs:

templates: ${{ steps.filter.outputs.changes }}

steps:

- uses: dorny/paths-filter@v2

id: filter

with:

filters: |

test:

needs: [detect-changes]

runs-on: ubuntu-latest

continue-on-error: true

strategy:

matrix:

templates: ${{ fromJSON(needs.detect-changes.outputs.templates) }}

steps:

- uses: actions/checkout@v3

- name: Smoke test for '${{ matrix.templates }}'

id: smoke_test

uses: ./.github/actions/smoke-test

with:

template: "${{ matrix.templates }}"

MIT License

Copyright (c) 2022 Microsoft Corporation

Permission is hereby granted, free of charge, to any person obtaining a copy

of this software and associated documentation files (the "Software"), to deal

in the Software without restriction, including without limitation the rights

to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

copies of the Software, and to permit persons to whom the Software is

furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

This repository contains a _collection_ of two Templates - `hello` and `color`. These Templates serve as simple template implementations which helps containerize the project. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `src` folder. Each Template has its own sub-folder, containing at least a `devcontainer-template.json` and `.devcontainer/devcontainer.json`.

All available options for a Template should be declared in the `devcontainer-template.json`. The syntax for the `options` property can be found in the [devcontainer Template json properties reference](https://containers.dev/implementors/templates#devcontainer-templatejson-properties).

For example, the `color` 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"

}

}

}

An [implementing tool](https://containers.dev/supporting#tools) will use the `options` property from [the documented Dev Container Template properties](https://containers.dev/implementors/templates#devcontainer-templatejson-properties) for customizing the Template. See [option resolution example](https://containers.dev/implementors/templates#option-resolution-example) for details.

**Note**: *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/<template>/README.md` per Template (which merges any existing `src/<template>/NOTES.md`).

Templates are individually versioned by the `version` attribute in a Template's `devcontainer-template.json`. Templates are versioned according to the semver specification. More details can be found in [the Dev Container Template specification](https://containers.dev/implementors/templates-distribution/#versioning).

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

This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) 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 an [implementing tool](https://containers.dev/supporting#tools) with:

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 as `private`.

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

Next you will need to add your Templates collection to our [public index](https://containers.dev/templates) so that other community members can find them. Just follow these steps once per collection you create:

* 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/templates/codespaces) surface Templates for their Dev Container Creation Configuration UI.

This repo contains a GitHub Action [workflow](.github/workflows/test-pr.yaml) for testing the Templates. Similar to the [`devcontainers/templates`](https://github.com/devcontainers/templates) repo, this repository has a `test` folder. Each Template has its own sub-folder, containing at least a `test.sh`.

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

This repo contains a GitHub Action [workflow](.github/workflows/release.yaml) that will automatically generate documentation (ie. `README.md`) for each Template. This file will be auto-generated from the `devcontainer-template.json` and `NOTES.md`.

{

"name": "Favorite color",

"image": "mcr.microsoft.com/devcontainers/base:${templateOption:imageVariant}",

// 👇 Features to add to the Dev Container. More info: https://containers.dev/implementors/features.

// "features": {},

// 👇 Use 'forwardPorts' to make a list of ports inside the container available locally.

// "forwardPorts": [],

"postCreateCommand": "echo '${templateOption:favorite}' > /tmp/color.txt"

// 👇 Configure tool-specific properties.

// "customizations": {},

// 👇 Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.

// "remoteUser": "root"

}

A Template to remind you of your favorite color

| Options Id | Description | Type | Default Value |

|-----|-----|-----|-----|

| imageVariant | Debian version (use bullseye on local arm64/Apple Silicon): | string | bullseye |

| favorite | Choose your favorite color. | string | red |

_Note: This file was auto-generated from the [devcontainer-template.json](https://github.com/devcontainers/template-starter/blob/main/src/color/devcontainer-template.json). Add additional notes to a `NOTES.md`._