Running the devcontainer CLI in GitHub Actions

You want CI to run against the exact environment developers use. This page runs the Dev Container CLI in GitHub Actions — via the official devcontainers/ci action or the CLI directly — so your build and tests execute inside the committed .devcontainer/, not a separate runner setup.

Prerequisites

You need a GitHub repo with a committed devcontainer config.

  • A committed .devcontainer/devcontainer.json.
  • A GitHub Actions workflow file.
  • Optionally a registry for build caching.

Actions prerequisitesYou need checkout, the CI action, a run command, and a layer cache.checkoutrepo + configdevcontainers/cibuildrunCmdtests insidecacheFromreuse layers

Step-by-Step Implementation

  1. Add the devcontainers/ci action to build and run inside the container.
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: devcontainers/ci@v0.3
        with:
          runCmd: npm ci && npm test
  1. Add layer caching with a registry image.
        with:
          cacheFrom: ghcr.io/acme/dev-image
          push: never
  1. Or use the CLI directly if you need finer control.
npm i -g @devcontainers/cli
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . -- npm test
  1. Confirm the logs show a build from .devcontainer/.

Actions job modelThe job checks out, builds the devcontainer, runs tests inside it, and caches layers.checkoutbrings the configbuilddevcontainer uprunCmdtests via execcachecacheFrom registry

Common Pitfalls

Actions failures are a missing config, host-run tests, or no cache.

Actions triageA triage path from a host-run CI to one that builds and tests inside the devcontainer.Does the job build .devcontainer/?NOUse devcontainers/ci or the CLIDo tests run via exec/runCmd?YEScacheFrom setCI matches developers

SymptomRoot CauseRemediation
Tests run on the runner, not the containerRan outside runCmd/execUse runCmd or devcontainer exec
Every run rebuilds fullyNo cacheFromAdd a registry cache image
Config not foundWrong workspace folderPoint at the repo root
Slow base pullsCold pull each runUse a prebuilt or cached image

Conclusion

The devcontainers/ci action (or the CLI) makes GitHub Actions build and test inside your committed .devcontainer/, so CI and developers share one environment. Add a registry layer cache and the pipeline is both faithful and fast.

Action responsibilitiesThe action builds and runs inside the config; you provide the config, command, and cache.The action givesBuild from configrunCmd insideLayer cachingYou provideCommitted configA test commandA cache image

FAQ

Should I use the action or the CLI? The devcontainers/ci action is simplest for common cases — it wraps build, run, and caching behind a few inputs. Use the CLI directly when you need finer control, such as running multiple exec steps or custom lifecycle handling. Both build the same committed config.

How do I run tests inside the container in Actions? Put your command in the action's runCmd (for example npm ci && npm test), or with the CLI run devcontainer exec -- npm test after devcontainer up. Either executes against the container's toolchain rather than the runner's host.

How do I make CI builds fast? Set cacheFrom to a registry image so the build reuses layers between runs, and publish a prebuilt dev image on a schedule so CI pulls it. Caching turns a cold multi-minute build into a fast pull-and-run.