devcontainers / action

GitHub Action to build & publish your own dev container assets

Development Container Action

Development Container Action A GitHub Action to publish development container assets.

This action is used to package and generate documentation for dev container Features and Templates.

Running this action will publish dev container Features and templates in accordance with following specifications:

• Dev container Feature distribution specification
• Dev container Template distribution specification

This action is used in the devcontainer/features repo, in the release.yaml workflow.

Usage

See the action.yml for available options.

To best get started, create your own repo from the devcontainers/feature-starter or devcontainers/template-starter repos, customize the provided examples, and trigger the release.yaml workflow.

Pinning devcontainer CLI version

This action heavily relies on the devcontainers/cli for various operations. By default, this action will fetch the latest version published to npm. The devcontainer-cli-version property can be used to pin to a specific CLI release. Eg:

- name: "Publish Features"
  uses: devcontainers/action@v1
  with:
    publish-features: "true"
    base-path-to-features: "./src"
    devcontainer-cli-version: "0.53.0"

The changelog for the CLI can always be found here: https://github.com/devcontainers/cli/blob/main/CHANGELOG.md

Design

Internally, this GitHub Action will fetch the latest published version of the Dev Container CLI and execute the appropriate CLI commands - namely devcontainer features publish and devcontainer templates publish.

action's Issues

Action should immediately fail when it fails to PUT a tag

Issue mentioned here --> devcontainers/spec#61 (comment)

As the corresponding publish action showed a ✅ , the user would not realize that it failed to publish some tag. Need to fail the action as soon as CLI fails to PUT a tag.

// cc @eitsupi

`Example Usage` in README.md Generated Incorrectly

Just wanted to call out that the Example Usage section of README.md appears to generate incorrectly when "version" isn't one of the options; it still shows "version": latest as the only option.

Here's my devcontainer-feature.json
https://github.com/natescherer/devcontainers-custom-features/blob/550cf03ac41f85ffbe5bd0aa7fb2d0856a026751/src/powershell-resources/devcontainer-feature.json

And here's the README.md the action generated :
https://github.com/natescherer/devcontainers-custom-features/blob/550cf03ac41f85ffbe5bd0aa7fb2d0856a026751/src/powershell-resources/README.md

[publish-features] released feature doesn't point to the feature README, but repo README

A released feature points to the README at the repository root.
See https://github.com/snebjorn/devcontainer-feature/pkgs/container/devcontainer-feature%2Fchromium

I was expecting it to point to the README inside the src/<feature-name> folder.
Being this one https://github.com/snebjorn/devcontainer-feature/blob/main/src/chromium/README.md for the above mentioned feature.

desire to have a way to list relevant (changed) features

idk if this is the right spot to bring this up but hey 🤷‍♀️

I've recently found immense usefulness in being able to list which features changed and default to all of them if the changes cant be determined https://github.com/devcontainers-community/list-features (no its not very polished yet)

i notice that there seems to be an attempt to do this in the feature-starter repo:

   strategy:
      matrix:
        features: # 👈
          - color
          - hello
        baseImage:
          - debian:latest
          - ubuntu:latest
          - mcr.microsoft.com/devcontainers/base:ubuntu

I think it's very nice to be able to do this instead:

  list-features:
    outputs:
      relevant-features: ${{ steps.list-features.outputs.relevant-features }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - id: list-features
        uses: devcontainers-community/list-features@v2


    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.list-features.outputs.relevant-features) }}

# then do this
${{ matrix.id }} ${{ matrix.documentationURL }}

or this if you prefer to matrix your image too (disclaimer haven't tested this flow yet)

    strategy:
      fail-fast: false
      matrix:
        feature: ${{ fromJSON(needs.list-features.outputs.relevant-features) }}
        image:
          - debian:latest
          - ubuntu:latest
          - mcr.microsoft.com/devcontainers/base:ubuntu

# then do this
${{ matrix.feature.id }} ${{ matrix.image }} ${{ matrix.feature.documentationURL }}

used in a repo like this
https://github.com/devcontainers-community/npm-features/blob/main/.github/workflows/test-features.yml

demo of it in action
https://github.com/devcontainers-community/npm-features
ex:

id to see this thing into the official @devcontainers feaeture-starter or organization if that's possible. idk if this is completely breaking some kind of unspoken project ettiqute; i just want this thing to be "official" since it seems so cool.

Did all dependencies been reviewed for security?

For example, I noticed there're two jsonc related dependencies:

action/package.json

Line 34 in a1930bf

"jsonc-parser": "^3.2.0"

action/package.json

Line 46 in a1930bf

"jsonc": "^2.0.0",

The one in the devDependencies was published 5 years ago, and maintained by 1 developer.

I know it's not been used in the source code yet, but I'm curious about how the supply chain security works there.

Thanks :)

GitHub action should better support a one-per-repo publishing technique

ref: devcontainers/spec#178

This makes it difficult to use the test commands for folks that would like to developer features in a one-per-repo kind of manner

Feature caching with docker-compose

I have a project with a docker-compose based devcontainer setup.
I have a dockerfile for my devcontainer image as well as a number of features defined in the devcontainer.json.

I can't figure out how to get the caching to work for our github actions. It seems that everytime I use this devcontainer within github actions it spends ~5 minutes rebuilding the container and all of it's features.

Is there an example of caching setup properly with a docker-compose setup?

Templates: Update autogenerated docs to include `platforms` detail

When templates were located in microsoft/vscode-dev-containers, the platforms variable was used for the auto-generated README files.

Example 👇

Looks like we did migrate the variable so that it could be utilized for auto-generated docs, however, it seems to have slipped though the gaps - I'll update devcontainers/action to utilize it. Wondering, @jcbhmr would that be helpful?

Originally posted by @samruddhikhandale in devcontainers/templates#145 (comment)

Support named devcontainers

VSCode supports having multiple devcontainers in a project, which works by putting the devcontainer.json file in a subfolder of .devcontainer, such as .devcontainer/default/decontainer.json. If you have multiple subfolders (i.e. .devcontainer/my-other-env/devcontainer.json), VSCode will show a UI asking which one to use. It would be great if this action supported such configurations via a devcontainer-name input.

Error using dependsOn in a feature

Summary

We're building a devcontainer feature that includes a dependsOn another feature. This is causing failures using @devcontainers/action but seems to work with the devcontainers CLI.

The documentation says that dependsOn is a preview feature. Is there something I need to do to opt-in to preview features?

Our feature definition is here: https://github.com/radius-project/radius/blob/ae9d95267ce52193ef3cab6ae121faf43dea5a8f/deploy/devcontainer-feature/src/radcli/devcontainer-feature.json

Successful output with CLI

I'm able to successfully package the feature with the CLI.

❯ devcontainer features package deploy/devcontainer-feature/src --output-folder ../../../testing -f
[550 ms] @devcontainers/cli 0.54.2. Node.js v21.3.0. darwin 23.1.0 arm64.
[550 ms] Packaging feature collection...
[551 ms] Processing feature: radcli...
[562 ms] Packaged 1 features!

Failing with actions

The failing workflow is here: https://github.com/radius-project/radius/actions/runs/7183715348/workflow

Here's an example run: https://github.com/radius-project/radius/actions/runs/7183715348/job/19563129086

Output:

Run devcontainers/action@v1
  with:
    publish-features: true
    base-path-to-features: ./deploy/devcontainer-feature/src
    generate-docs: false
    disable-schema-validation: false
    validate-only: false
    disable-repo-tagging: false
    publish-templates: false
  env:
    GITHUB_TOKEN: ***
Validating Feature metadata...
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/onCreateCommand" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/onCreateCommand/additionalProperties" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/updateContentCommand" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/updateContentCommand/additionalProperties" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postCreateCommand" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postCreateCommand/additionalProperties" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postStartCommand" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postStartCommand/additionalProperties" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postAttachCommand" (strictTypes)
strict mode: use allowUnionTypes to allow union type keyword at "#/properties/postAttachCommand/additionalProperties" (strictTypes)
Error: (!) ERR: 'deploy/devcontainer-feature/src/radcli/devcontainer-feature.json' is not valid:
[
    {
        "instancePath": "",
        "schemaPath": "#/additionalProperties",
        "keyword": "additionalProperties",
        "params": {
            "additionalProperty": "dependsOn"
        },
        "message": "must NOT have additional properties"
    },
    {
        "instancePath": "",
        "schemaPath": "#/oneOf",
        "keyword": "oneOf",
        "params": {
            "passingSchemas": null
        },
        "message": "must match exactly one schema in oneOf"
    }
]

Provide better logging for when a `GITHUB_TOKEN` is required

Some functionality provided by this action, ie:

• repo tagging
• publishing to GHCR

requires providing a GITHUB_TOKEN (the actions token provided "for free" is usually enough).

This should be documented and if a token is not provided, a useful error should be provided.

cc/ @brendandburns

Issues when publishing images on GHCR due to uppercase letters

Hi, I was using the feature-starter setup to publish the features I've made to GitHub automatically through GitHub Actions but was unable to because namespaces don't support uppercase characters. For more context, the log during deploy says "Failed to get upload session ID", but the workflow is still marked as successful. There are no packages uploaded after the workflow run.

I've confirmed that the uppercase characters are the problem by attempting the process locally through the devcontainer CLI. Currently I am publishing features manually through the CLI by writing out the namespace in lowercase (e.g androoideka/container-setups), but it'd be convenient if this action also supported it. Since the action builds the namespace through GitHub metadata, I'm guessing the simplest way to solve this is to change lines 21 and 22 in utils.ts by appending toLowerCase() to both github.context.repo.owner and github.context.repo.repo

Thanks!

Extra blank line with each docs update

It adds an extra blank line at the beginning of the file if there are no changes.

For example: erdaltsksn/devcontainer#9

README should add info on extensions installed by default

The Terraform feature in its title, description and README seems that it has nothing specific to a provider but it installs Azure specific vscode extensions. The extensions installed with the feature are the "Azure Terraform" and "Azure Account" extensions.

As far as I can see, it's not possible to control the installation of extensions and settings from a feature, so I'm stuck with them if I would like to use the feature to install the rest of the terraform cli tools (the installation of the individual cli tools can be controlled from the feature options).

I propose to make the terraform feature provider neutral by removing those extensions from the feature. A separate feature can be created for installing Azure specific extensions for Terraform.

Fails when `devcontainer-feature.json` contains comments

devcontainers/action@v1 fails when devcontainer-feature.json contains comments.

SyntaxError: Unexpected token / in JSON at position 274
    at JSON.parse (<anonymous>)
    at packageCollection (/usr/local/lib/node_modules/@devcontainers/cli/dist/spec-node/collectionCommonUtils/packageCommandImpl.js:[17](https://github.com/snebjorn/devcontainer-feature/actions/runs/3211796200/jobs/5250216647#step:3:18)7:35)
    at async packageFeatureCollection (/usr/local/lib/node_modules/@devcontainers/cli/dist/spec-node/featuresCLI/packageCommandImpl.js:49:12)
    at async doFeaturesPackageCommand (/usr/local/lib/node_modules/@devcontainers/cli/dist/spec-node/featuresCLI/packageCommandImpl.js:26:26)
    at async featuresPublish (/usr/local/lib/node_modules/@devcontainers/cli/dist/spec-node/featuresCLI/publish.js:72:22)
    at async /usr/local/lib/node_modules/@devcontainers/cli/dist/spec-node/featuresCLI/publish.js:45:[18](https://github.com/snebjorn/devcontainer-feature/actions/runs/3211796200/jobs/5250216647#step:3:19)

Node.js 12 actions are deprecated

The GitHub Actions workflow gives the following error while running the action:

Node.js 12 actions are deprecated. For more information see: github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12.

Auto generate a top-level `README.md`

Just like we generate documentation for each Feature, auto-generate the repo-level README with pointers to the individual README docs.

Feature Request: Publish Image

Note

Not sure if this conversation belongs here.

Feature Request

Add a github action to publish docker images created by devcontainer build.

Where

By default, publish to ghcr.io/<username>/<repo>/devcontainer or similar.

Why

This seems like an easy win to share builds in large teams.

Up Next

Add a cli flag that will automatically pull the ghcr.io image.

$ devcontainer build --pull                       # will look for the latest image in the default ghcr.io location
$ devcontainer build --pull mcr.microsoft.com/devcontainers/action:latest  # or a specified repository

Schema validation for `devcontainer-feature.json` during publishing stage

Add validation for the devcontainer-feature.json (make sure properties match schema, etc..). This change likely needs to be made in the devcontainers/cli repo, but will be observed here during publishing.

related: devcontainers/spec#140

Changed namespace, but version tags still appear in original namespace

I published the first several versions of our devcontainer feature without setting features-namespace or templates-namespace, so they appeared at a default location based on the name of the repository:
https://github.com/tailscale/codespace/pkgs/container/codespace%2Ftailscale

I've since updated our workflow to set the namespaces, but new version tags still only appear at the original location.

For example I ran the devcontainers/action workflow for 1.0.3 after updating features-namespace and templates-namespace, but the 1.0.3 tag only appears in the old package location:
https://github.com/tailscale/codespace/pkgs/container/codespace%2Ftailscale

The new location, the one that I actually want to publish to, only gets the latest tag.
https://github.com/tailscale/codespace/pkgs/container/codespace

Therefore the prior versions drop out of its view when a new one it published, and it isn't possible for people to reference the devcontainer feature by a specific version.

What I'd like to accomplish is:

• stop adding new versions in https://github.com/tailscale/codespace/pkgs/container/codespace%2Ftailscale, but leave it in place so as not to break people who are already referencing it
• new versions appear only in https://github.com/tailscale/codespace/pkgs/container/codespace, with their tags

Is there a way to accomplish this?

References: devcontainers/devcontainers.github.io#127

Permission denied during publish feature when putting manifest for tag

I try to publish a feature but I receive the error, that the permission for putting a tag is denied.

[2023-05-10T16:35:29.313Z] @devcontainers/cli 0.41.0. Node.js v18.16.0. linux 5.15.0-1037-azure x64.
[2023-05-10T16:35:29.313Z] Packaging feature collection...
[2023-05-10T16:35:29.315Z] Processing feature: xxx...
[2023-05-10T16:35:29.331Z] Packaged 1 features!
[2023-05-10T16:35:29.332Z] Processing feature: xxx...
[2023-05-10T16:35:29.332Z] Fetching published versions...
[2023-05-10T16:35:29.530Z] Publishing versions: 1,1.0,1.0.0,latest...
[2023-05-10T16:35:29.532Z] sha256:4fe7edad8512422c90f2d4448d187de7598c6985e5a1d2b8b8a06277a722199b (size: 6144)
[2023-05-10T16:35:29.532Z] Computed Content-Digest ->  sha256:6cf53cd32f1f5025a601586967323dd3cdf574ce6b0df268e564f6a09d38775b (size: 64)
[2023-05-10T16:35:29.838Z] Starting PUT of tgzLayer blob 'sha256:4fe7edad8512422c90f2d4448d187de7598c6985e5a1d2b8b8a06277a722199b' (size=6144)
[2023-05-10T16:35:30.606Z] Tagged: 1 -> /v2/xxx/manifests/sha256:6cf53cd32f1f5025a601586967323dd3cdf574ce6b0df268e564f6a09d38775b
[2023-05-10T16:35:30.754Z] Failed to PUT manifest for tag 1.0
{
    "errors": [
        {
            "code": "DENIED",
            "message": "permission_denied: write_package"
        }
    ]
}
[2023-05-10T16:35:30.754Z] (!) ERR: Failed to publish feature: 'xxx'
[2023-05-10T16:35:30.754Z] (!) ERR: Failed to publish 'xxx'

The package setting is public and the workflow has r/w permissions and has the permission to create PRs.

Make your action Verified

I am not sure what is required but it would be nice if your actions had the Verified flag in the Marketplace. Enterprises and Organizations can limit the Allowed Actions to only those that are Verified.

Validate fails with comments

#75

I guess this is not fixed:

{
    "name": "debug-comments",
    "id": "debug-comments",
    "version": "1.0.0",
    "description": "",
    "mounts": [
        // "source=/dev/bus/usb,target=/dev/bus/usb,type=bind,readonly"
        {
            "source": "/dev/bus/usb",
            "target": "/dev/bus/usb",
            "type": "bind"
        }
    ],
    "installsAfter": [
        "ghcr.io/devcontainers/features/common-utils"
    ]
}

The cli works well:

$ devcontainer features package -f ./src/debug-comments
@devcontainers/cli 0.56.1. Node.js v20.11.0. linux 6.6.16 x64.
Packaging single feature...
Packaged feature 'debug-comments'

But the action does not:

jobs:
    validate:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v4

            - name: 'Validate devcontainer-feature.json files'
              uses: devcontainers/action@v1
              with:
                  validate-only: 'true'
                  base-path-to-features: './src'

undefined:7
        // "source=/dev/bus/usb,target=/dev/bus/usb,type=bind,readonly"
        ^

SyntaxError: Unexpected token / in JSON at position 131
    at JSON.parse (<anonymous>)
    at /home/runner/work/_actions/devcontainers/action/v1/dist/index.js:18623:39
    at Generator.next (<anonymous>)
    at fulfilled (/home/runner/work/_actions/devcontainers/action/v1/dist/index.js:18485:58)

It seems that action uses JSON.parse for JSON with comments, it's not the bug of the cli.

Cannot find .tgz file when publish-templates: "true"

I have tried different ways to publish the devcointainer: (https://github.com/Pwd9000-ML/devcontainer-templates)

But I get this error every time: https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418

The error is not overly helpful in this case:

Publishing templates...
Fetching the latest @devcontainer/cli...
/usr/local/bin/devcontainer templates publish -r ghcr.io -n Pwd9000-ML/devcontainer-templates ./src
[2023-01-17T[14](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:15):49:35.949Z] @devcontainers/cli 0.27.1. Node.js v16.19.0. linux 5.[15](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:16).0-1030-azure x64.
[2023-01-17T14:49:35.949Z] Packaging template collection...
[2023-01-17T14:49:35.951Z] Processing template: github-actions-runner-devcontainer...
[2023-01-17T14:49:35.978Z] Packaged 1 templates!
[2023-01-17T14:49:35.979Z] Processing template: github-actions-runner...
[2023-01-17T14:49:35.979Z] Fetching published versions...
[2023-01-17T14:49:36.159Z] Publishing versions: 0,0.1,0.1.1,latest...
[2023-01-17T14:49:36.159Z] Blob /tmp/templates-output-[16](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:17)73966975947/devcontainer-template-github-actions-runner.tgz does not exist.
[2023-01-[17](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:18)T14:49:36.159Z] (!) ERR: Failed to publish template: 'ghcr.io/pwd9000-ml/devcontainer-templates/github-actions-runner'
[[20](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:21)[23](https://github.com/Pwd9000-ML/devcontainer-templates/actions/runs/3940393359/jobs/6741443418#step:3:24)-01-17T14:49:36.159Z] (!) ERR: Failed to publish 'ghcr.io/Pwd9000-ML/devcontainer-templates/github-actions-runner'
Error: The process '/usr/local/bin/devcontainer' failed with exit code 1
Error: (!) Failed to publish templates.

Tests are passing OK.

Upgrade to Node20

Is there any timeline for an update to Node 20 as Node 16 is out of support since September 11th?
https://nodejs.org/en/blog/announcements/nodejs16-eol

Thanks

Default `false` values for `boolean` parameters results in `-`

Due to this line in the action not differentiating false vs. undefined, the generated markdown parameter table shows - for params which have a default of false. For example, in the java docs:

GitHub URL from context

Hi, for using this in a GitHub enterprise context it would be necessary to get the base url from the context instead of hardcoding it to github.com

action/src/generateDocs.ts

Line 120 in 5002ae5

urlToConfig = `https://github.com/${srcInfo.owner}/${srcInfo.repo}/blob/main/${basePathTrimmed}/${f}/${metadataFile}`;

I think it should be available from here

https://github.com/actions/toolkit/blob/04945c6048e796f86b5c4cf1965faa378af67480/packages/github/src/context.ts#L23C5-L23C5

Sorry that I currently am not able to directly do a PR for that.

Split the generateDocs as lib or cli

So we can use it everywhere not only in the GitHub Actions :)

A simple PoC here: https://github.com/hellodword/action/tree/patch-3

Try it with:

npx ts-node ./src/cli/main.ts features docs --owner ohhh --repo wuw ./__tests__/examples/simple/src

And, would it be better to implement generateDocs and validate things in the upstream cli?

devcontainer features validate
devcontainer features docs
devcontainer templates validate
devcontainer templates docs
...

Two implementations always have differences.

Example Usage Templates

Wanted to get some thoughts about maybe adding templates for the Example Usage section, similar to the use of NOTES.md. As it stands now, this action overwrites the Example Usage section each time it runs, which is less than ideal.

I was thinking maybe an EXAMPLES.json file like the following:

{
    "optionSets": [
        {
            "optionOne": "valueOne"
        },
        {
            "optionTwo": "valueTwo"
        }
    ]
}

If this seems agreeable, I could cook up a PR for this, I think.

[publish-features] releases dev container (non-devcontainer-feature) from root of repo

The setup given by the feature-template correctly releases features pointed to by base-path-to-features: "./src".

However it also releases the .devcontainer.json located at the root of the repo which is not located in ./src. It's not even a devcontainer-feature.

See this repo for details https://github.com/snebjorn/devcontainer-feature

Notice it released 2 packages

consider split into multiple actions?

hello! 👋

problem: what if a company, org, or institution theoretically wants to do this:

(this is THEORETICAL and i haven't actually encountered this)

but only for the docs generation part. or only for the publishing part. or only for publishing features but not templates... what do they do? its all or nothing since everything is in this single action 🤣

i notice that this organization very much favors monorepo pattern so i dont know if this is even remotely possible 🤷‍♀️ but its something id like to see considered 😀