devcontainers/ci

If your devcontainer.json uses localEnv references within the remoteEnv section, you must define those variables using the env property on the GitHub Action step itself, rather than the env property nested under the with block.

Because localEnv references are resolved by the devcontainer CLI, setting them in the action's env block ensures they are available in the correct context for resolution. If you attempt to set them inside the with.env block, they may be overridden by the localEnv resolution process when the CLI starts the container.

// devcontainer.json
{
    "remoteEnv": {
        "HELLO": "${localEnv:HELLO}"
    }
}

# GitHub Action Workflow
      - name: Build and run dev container task
        uses: devcontainers/ci@v0.3
        env:
          # Set HELLO here so that it is resolved via the localEnv context
          HELLO: hello
        with:
          imageName: ghcr.io/example/example-devcontainer
          runCmd: echo "$HELLO"
          # Don't use the env block here to set the HELLO environment variable
          # as it will be overridden by the value from localEnv context

For faster and more reliable builds, use a matrix strategy to run builds on native runners for each architecture. This avoids the overhead and compatibility issues of QEMU emulation.

Workflow Pattern

1. Build Jobs: Run parallel jobs on native runners (e.g., ubuntu-latest for AMD64 and ubuntu-24.04-arm for ARM64).
   • Set useNativeRunner: true.
   • Provide a single platform value (e.g., linux/arm64).
   • Set push: always to ensure platform-specific images are available for the merge step.
   • The system automatically tags images with a suffix derived from the platform (e.g., linux/arm64 becomes linux-arm64).
2. Merge Job: Runs after all build jobs complete. It uses a dedicated merge tool to combine the individual platform images into a single multi-arch manifest.

Benefits

• Speed: Native compilation is much faster than emulation.
• Reliability: Avoids QEMU-related bugs.
• Flexibility: Works with GitHub hosted ARM runners or self-hosted ARM agents in Azure DevOps.

# GitHub Actions Matrix Example
jobs:
  build:
    strategy:
      matrix:
        include:
          - runner: ubuntu-latest
            platform: linux/amd64
          - runner: ubuntu-24.04-arm
            platform: linux/arm64
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: devcontainers/ci@v0.3
        with:
          imageName: ghcr.io/example/myimage
          platform: ${{ matrix.platform }}
          useNativeRunner: true
          push: always

  manifest:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: devcontainers/ci/merge@v0.3
        with:
          imageName: ghcr.io/example/myimage
          platforms: linux/amd64,linux/arm64

If your devcontainer.json uses localEnv references in the remoteEnv section, you must define those variables using the task's top-level env property rather than the env input nested under the with block.

Defining them at the task level ensures the devcontainer CLI can resolve the ${localEnv:VAR_NAME} syntax correctly. If you define them inside the inputs.env block, they may be overridden by the localEnv resolution process when the container starts.

// devcontainer.json
{
    "remoteEnv": {
        "HELLO": "${localEnv:HELLO}"
    }
}

# Azure DevOps Task Configuration
- task: DevcontainersCi@0
  env:
    # Set HELLO here so that it is resolved via the localEnv context
    HELLO: hello
  inputs:
    imageName: 'yourregistry.azurecr.io/example-dev-container'
    runCmd: echo "$HELLO"
    # Don't use the env block here to set the HELLO environment variable
    # as it will be overridden by the value from localEnv context
    # when the CLI starts the container

To avoid rebuilding the image from scratch on every run, you can push the built image to a container registry (e.g., GitHub Container Registry) and use it as a cache.

When imageName is provided, the action defaults to a push strategy of filter. This means if the run succeeds (and is not from a PR branch), the image is pushed to the registry. Subsequent builds will then use these layers as a cache to improve performance.

      - name: Login to GitHub Container Registry
        uses: docker/login-action@v2 
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and run Dev Container task
        uses: devcontainers/ci@v0.3
        with:
          # Specify the full image name including registry
          imageName: ghcr.io/example/example-devcontainer
          runCmd: |
            make install-packages
            make ci-build