feat: add image variant with vscode specific settings (#314)

rjaegers · web-flow · commit 8b9c70764014 · 2024-02-20T11:50:57.000Z
* feat: add image variant with vscode specific settings

* chore: fix sign command for vscode container

* chore(devcontainer.json): remove unnecessary properties for this container

* chore: externalize metadata and extend contents

* ci: add checkout step to build-push

* chore: quote label data

* chore: simplify devcontainer-metadata-vscode.json

* chore: add back one extension

* chore: add more plug-ins

* chore: try to fix array escaping

* chore: use jq tostring to convert json to label

* chore: debug json magic

* chore: escape, quote, unescape, doule escape... for victory

* chore: hard-code metadata for now, I give up

* chore: single quote content of label to prevent shell interpolation

* chore: running out of ideas

* chore: why can't you leave my quotes alone

* ci: final victory

* chore: add vscode settings

* chore: change path to compile_commands

* chore: update vscode plugin versions

* chore: update documentation

* docs: minor update on merge logic for devcontainer.metadata
diff --git a/.devcontainer/devcontainer-metadata-vscode.json b/.devcontainer/devcontainer-metadata-vscode.json
@@ -0,0 +1,33 @@
+[
+  {
+    "remoteEnv": { "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}" },
+    "customizations": {
+      "vscode": {
+        "extensions": [
+          "llvm-vs-code-extensions.vscode-clangd@0.1.26",
+          "marus25.cortex-debug@1.12.1",
+          "matepek.vscode-catch2-test-adapter@4.8.3",
+          "mhutchie.git-graph@1.30.0",
+          "ms-vscode.cmake-tools@1.17.15",
+          "ms-vscode.cpptools@1.18.5",
+          "ms-vsliveshare.vsliveshare@1.0.5905",
+          "SonarSource.sonarlint-vscode@4.3.0",
+          "xaver.clang-format@1.9.0"
+        ]
+      },
+      "settings": {
+        "C_Cpp.intelliSenseEngine": "disabled",
+        "C_Cpp.formatting": "clangFormat",
+        "clangd.arguments": [
+          "--query-driver=/opt/**/arm-none-eabi-*",
+          "--compile-commands-dir=${userHome}/.amp"
+        ],
+        "cmake.copyCompileCommands": "${userHome}/.amp/compile_commands.json",
+        "cmake.options.statusBarVisibility": "compact",
+        "cortex-debug.gdbPath": "gdb-multiarch",
+        "cortex-debug.objdumpPath": "arm-none-eabi-objdump",
+        "sonarlint.pathToCompileCommands": "${userHome}/.amp/compile_commands.json"
+      }
+    }
+  }
+]
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -3,8 +3,6 @@
     "dockerfile": "Dockerfile",
     "context": ".."
   },
-  "runArgs": ["--add-host=host.docker.internal:host-gateway"],
-  "remoteEnv": { "LOCAL_WORKSPACE_FOLDER": "${localWorkspaceFolder}" },
   "mounts": [
     "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
   ],
diff --git a/.github/workflows/build-push.yml b/.github/workflows/build-push.yml
@@ -29,10 +29,23 @@ jobs:
       # with sigstore/fulcio when running outside of PRs.
       id-token: write
     steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
       - uses: sigstore/cosign-installer@e1523de7571e31dbe865fd2e80c5c7c23ae71eb4 # v3.4.0
         if: ${{ github.event_name != 'merge_group' }}
+      - uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3 # v3.0.0
+      - uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
+        with:
+          version: v0.12.1
+      - uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+        if: ${{ github.event_name != 'merge_group' }}
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
       - uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
-        id: meta
+        id: metadata-base
         env:
           DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
         with:
@@ -45,43 +58,68 @@ jobs:
             type=semver,pattern={{version}}
             type=semver,pattern={{major}}.{{minor}}
             type=semver,pattern={{major}}
-      - uses: docker/setup-qemu-action@68827325e0b33c7199eb31dd4e31fbe9023e06e3 # v3.0.0
-      - uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
+      - uses: docker/build-push-action@4a13e500e55cf31b7a5d59a38ab2040ab0f42f56 # v5.1.0
+        id: build-and-push-base
         with:
-          version: v0.12.0
-      - uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
-        if: ${{ github.event_name != 'merge_group' }}
+          file: .devcontainer/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'merge_group' }}
+          tags: ${{ steps.metadata-base.outputs.tags }}
+          labels: ${{ steps.metadata-base.outputs.labels }}
+          annotations: ${{ steps.metadata-base.outputs.annotations }}
+          sbom: true
+          provenance: true
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+      - uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
+        id: metadata-vscode
+        env:
+          DOCKER_METADATA_ANNOTATIONS_LEVELS: manifest,index
         with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          images: ${{ env.REGISTRY }}/${{ github.repository }}-vscode
+          # Generate Docker tags based on the following events/attributes
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=pr
+            type=semver,pattern={{raw}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+      # Generate image LABEL for devcontainer.metadata
+      # the sed expression is a workaround for quotes being eaten in arrays (e.g. ["x", "y", "z"] -> ["x",y,"z"])
+      - run: echo "metadata=$(jq -cj '.' .devcontainer/devcontainer-metadata-vscode.json | sed 's/,"/, "/g')" >> "$GITHUB_OUTPUT"
+        id: devcontainer-metadata
       - uses: docker/build-push-action@4a13e500e55cf31b7a5d59a38ab2040ab0f42f56 # v5.1.0
-        id: build-and-push
+        id: build-and-push-vscode
         with:
           file: .devcontainer/Dockerfile
           platforms: linux/amd64,linux/arm64
           push: ${{ github.event_name != 'merge_group' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          annotations: ${{ steps.meta.outputs.annotations }}
+          tags: ${{ steps.metadata-vscode.outputs.tags }}
+          labels: |
+            ${{ steps.metadata-vscode.outputs.labels }}
+            devcontainer.metadata=${{ steps.devcontainer-metadata.outputs.metadata }}
+          annotations: ${{ steps.metadata-vscode.outputs.annotations }}
           sbom: true
           provenance: true
           cache-from: type=gha
-          cache-to: type=gha,mode=max
       - uses: anchore/sbom-action@b6a39da80722a2cb0ef5d197531764a89b5d48c3 # v0.15.8
-        if: ${{ steps.build-and-push.outputs.digest != '' && github.event_name != 'merge_group' }}
+        if: ${{ steps.build-and-push-base.outputs.digest != '' && github.event_name != 'merge_group' }}
         with:
-          image: ${{ env.REGISTRY }}/${{ github.repository }}@${{ steps.build-and-push.outputs.digest }}
+          image: ${{ env.REGISTRY }}/${{ github.repository }}@${{ steps.build-and-push-base.outputs.digest }}
           dependency-snapshot: true
       - uses: actions/dependency-review-action@be8bc500ee15e96754d2a6f2d34be14e945a46f3 # v4.1.2
         if: ${{ github.event_name == 'pull_request' }}
         with:
           comment-summary-in-pr: on-failure
           fail-on-severity: critical
-      - name: Sign the image with GitHub OIDC token
+      - name: Sign the images with GitHub OIDC token
         if: ${{ github.event_name != 'merge_group' }}
         # This step uses the GitHub OIDC identity token to provision an ephemeral certificate
         # against the sigstore community Fulcio instance.
         env:
-          DIGEST: ${{ steps.build-and-push.outputs.digest }}
-        run: cosign sign --yes --recursive "${{ env.REGISTRY }}/${{ github.repository }}@${DIGEST}"
+          DIGEST_BASE: ${{ steps.build-and-push-base.outputs.digest }}
+          DIGEST_VSCODE: ${{ steps.build-and-push-vscode.outputs.digest }}
+        run: |
+          cosign sign --yes --recursive "${{ env.REGISTRY }}/${{ github.repository }}@${DIGEST_BASE}"
+          cosign sign --yes --recursive "${{ env.REGISTRY }}/${{ github.repository }}-vscode@${DIGEST_VSCODE}"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,6 +23,8 @@ jobs:
       # While the docker/build-push-action works from the Git context, we still need
       # the checkout step for running our tests.
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+        with:
+          persist-credentials: false
       - uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
       - uses: docker/build-push-action@4a13e500e55cf31b7a5d59a38ab2040ab0f42f56 # v5.1.0
         with:
diff --git a/.github/workflows/cleanup-pr-image.yml b/.github/workflows/cleanup-pr-image.yml
@@ -23,9 +23,16 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - run: cosign clean -f --type=signature "${{ env.REGISTRY }}/${{ github.repository }}:pr-${{ github.event.pull_request.number }}"
+      - run: cosign clean -f --type=signature "${{ env.REGISTRY }}/${{ github.repository }}-vscode:pr-${{ github.event.pull_request.number }}"
       - uses: bots-house/ghcr-delete-image-action@3827559c68cb4dcdf54d813ea9853be6d468d3a4 # v1.1.0
         with:
           owner: ${{ github.repository_owner }}
           name: ${{ github.event.repository.name }}
           token: ${{ secrets.GITHUB_TOKEN }}
           tag: pr-${{ github.event.pull_request.number }}
+      - uses: bots-house/ghcr-delete-image-action@3827559c68cb4dcdf54d813ea9853be6d468d3a4 # v1.1.0
+        with:
+          owner: ${{ github.repository_owner }}
+          name: ${{ github.event.repository.name }}-vscode
+          token: ${{ secrets.GITHUB_TOKEN }}
+          tag: pr-${{ github.event.pull_request.number }}
diff --git a/README.md b/README.md
@@ -14,59 +14,95 @@ This repository is under active development; see [pulse](https://github.com/phil
 
 ## Description
 
+### Image variants
+
+Two devcontainers are published towards the [GitHub Container Registry](https://ghcr.io/):
+
+- [amp-devcontainer](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer); the base container including all tools mentioned below
+- [amp-devcontainer-vscode](https://github.com/orgs/philips-software/packages/container/package/amp-devcontainer-vscode); as above, but including a full [Visual Studio Code](https://code.visualstudio.com/) configuration that is compatible with [GitHub Codespaces](https://github.com/features/codespaces)
+
+### amp-devcontainer
+
 The amp-devcontainer built from this repository contains compilers and tools to facilitate modern (embedded) C++ development.
 The amp-devcontainer includes support for host- and cross-compilation using gcc, arm-gcc and clang compilers.
 Next to the compilers there is support for code-coverage measurement, mutation testing (using [mull](https://github.com/mull-project/mull)), fuzzing (using [libfuzzer](https://www.llvm.org/docs/LibFuzzer.html)) and static analysis (clang-format, clang-tidy, clangd, include-what-you-use).
 The default build system is set up to use CMake, Ninja and CCache.
 
 For the full list of all included tools and tool versions see the [Dependency Graph](https://github.com/philips-software/amp-devcontainer/network/dependencies), the SBOM published with a [release](https://github.com/philips-software/amp-devcontainer/releases), or the SBOM attached to the image.
 
-## Build & Test
+### amp-devcontainer-vscode
 
-The container can be built and tested locally by importing this repository in VS Code with the `Dev Containers` (ms-vscode-remote.remote-containers) plug-in installed. As a prerequisite Docker needs to be installed on the host system. As an alternative a GitHub Codespace can be started.
+The amp-devcontainer-vscode is a, slightly more, opinionated variant that can be used in Visual Studio Code or GitHub Codespaces without any additional configuration. All included tools are set-up and necessary plug-ins will be installed at container start. This behavior is implemented by appending devcontainer metadata to an image label according to the [specifications](https://containers.dev/implementors/reference/#labels). It is possible to override, amend or change the options following this [merge logic](https://containers.dev/implementors/spec/#merge-logic).
 
-A test task is available to run the included `bats` tests. Choose `Tasks: Run Test Task` from the command pallette.
+## Usage
 
-## Verify image signature
+### Verify image signature
 
-The container image is signed with [SigStore](https://www.sigstore.dev/) [Cosign](https://docs.sigstore.dev/signing/quickstart/) using a keyless signing method.
+The container images are signed with [SigStore](https://www.sigstore.dev/) [Cosign](https://docs.sigstore.dev/signing/quickstart/) using a keyless signing method.
 
 The signature can be verified with the following command (using Docker), verifying that the image is actually signed by the GitHub CI system:
 
+> amp-devcontainer
+
 ```sh
 docker run --rm gcr.io/projectsigstore/cosign verify ghcr.io/philips-software/amp-devcontainer --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/philips-software/amp-devcontainer
 ```
 
-## Usage
+> amp-devcontainer-vscode
+
+```sh
+docker run --rm gcr.io/projectsigstore/cosign verify ghcr.io/philips-software/amp-devcontainer-vscode --certificate-oidc-issuer https://token.actions.githubusercontent.com --certificate-identity-regexp https://github.com/philips-software/amp-devcontainer
+```
+
+The resulting containers can be used in a `.devcontainer.json` file or in a `.devcontainer` folder.
 
-The resulting container can be used in a `.devcontainer` folder. While the example uses the `latest` tag, it is recommended to pin to a specific version. Or better yet, a specific SHA.
+> [!NOTE]
+> While the following examples use the `latest` tag, it is recommended to pin to a specific version. Or better yet, a specific SHA.
 
-> .devcontainer/devcontainer.json
+### amp-devcontainer
+
+> .devcontainer/devcontainer.json or .devcontainer.json
 
 ```json
 {
     "image": "ghcr.io/philips-software/amp-devcontainer:latest"
 }
 ```
 
+### amp-devcontainer-vscode
+
+> .devcontainer/devcontainer.json or .devcontainer.json
+
+```json
+{
+    "image": "ghcr.io/philips-software/amp-devcontainer-vscode:latest"
+}
+```
+
 ## Community
 
-This project uses the [CODE_OF_CONDUCT](./CODE_OF_CONDUCT.md) to define expected conduct in our community. Instances of
+This project uses a [code of conduct](./CODE_OF_CONDUCT.md) to define expected conduct in our community. Instances of
 abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project [CODEOWNER](./.github/CODEOWNERS)
 
 ## Changelog
 
-See [CHANGELOG](./CHANGELOG.md) for more info on what's been changed.
+See the [changelog](./CHANGELOG.md) for more info on what's been changed.
 
 ## Contributing
 
-See [CONTRIBUTING](./CONTRIBUTING.md)
+This project uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) and [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) please see the [contributing](./CONTRIBUTING.md) guideline for more information.
+
+### Build & Test
+
+The container can be built and tested locally by importing this repository in VS Code with the [`Remote Containers`](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) plug-in installed. As a prerequisite Docker needs to be installed on the host system. Alternatively a GitHub Codespace can be started.
+
+A test task is available to run the included `bats` tests. Choose `Tasks: Run Test Task` from the command pallette.
 
 ## Reporting vulnerabilities
 
 If you find a vulnerability, please report it to us!
-See [SECURITY.md](./SECURITY.md) for more information.
+See [security](./SECURITY.md) for more information.
 
 ## Licenses
 
-See [LICENSE](./LICENSE)
+See [license](./LICENSE)
