Devsy
Developing in a Workspace

Continuous Integration

devsy ci starts a devcontainer workspace and runs a command in it. It deletes a newly created workspace afterward unless you pass --keep, but never deletes a workspace that existed before the run. Use it to run tests inside the container and check the build of a newly created workspace.

How it works

  1. Devsy resolves a workspace from the current directory or a given source.
  2. Devsy builds and starts the devcontainer like devsy workspace up, without IDE or SSH config changes.
  3. Devsy runs the command inside the container.
  4. Devsy deletes the workspace, even when the command fails, unless you pass --keep. Devsy never deletes a workspace that existed before the run.

The command's exit code becomes the exit code of devsy ci, so a failing test fails the CI job.

Usage

devsy ci [flags] [workspace-path|workspace-name] -- <cmd> [args...]

Run the test suite inside the devcontainer for the current project:

devsy ci -- make test

Target a specific project folder and pass environment variables:

devsy ci ./service -- npm test
devsy ci --remote-env CI=true --remote-env NODE_ENV=test -- npm test

Select a named config, such as a .devcontainer/<name> profile:

devsy ci --devcontainer id:ci -- make test

Keep the workspace after the run, for debugging:

devsy ci --keep -- ./run-integration-tests.sh

Common flags

Run devsy ci --help for the full list. Common flags:

  • --keep keeps the workspace after the run, whether the command succeeds or fails.
  • --remote-env KEY=VALUE sets an environment variable in the container at run time. Repeatable.
  • --devcontainer picks the config: none, image:<ref>, id:<name>, or a path to a devcontainer.json.
  • --cache-from and --no-cache control the image build cache.
  • --platform runs the container under another platform, such as linux/amd64.
  • --secret, --env, --build-secret, and --git-token inject stored Devsy secrets and variables. See Secrets.

Control progress output

--no-status hides Devsy's live progress messages. It does not filter diagnostics or the command's own output.

OutputEffect of --no-status
Devsy progressHidden, including progress from the nested workspace command
Devsy diagnosticsStill controlled by --quiet, --log-level, and diagnostic format
Command stdout and stderrPreserved on their original streams
Recorded eventsStill recorded where the command already records them

For example, keep warnings and errors while hiding progress:

devsy ci --no-status --result-format=plain --log-level=warn . -- bash .tools/test.sh

To show only errors, use --quiet instead. It takes precedence over --log-level=warn and suppresses warnings too:

devsy ci --no-status --result-format=plain --quiet . -- bash .tools/test.sh

When stdout is redirected, use --result-format=plain to keep the success result JSON off stderr. Use --result-format=json when the caller needs the structured result.

Setup history after cleanup

devsy ci deletes the workspace, but Devsy keeps the build and lifecycle hook history in the local store. Read it by run ID after the job ends, or from an artifact step on the same machine:

devsy workspace logs --source setup --list
devsy workspace logs --source setup --run RUN_ID --context CONTEXT --result-format=plain

Retention is limited. See Setup history. The history covers the build and lifecycle hooks. The stdout and stderr of your command after -- stay on their normal streams. Devsy does not wait for hooks still running when the command ends.

Build and push images

To build and publish a devcontainer image for reuse as a build cache, run devsy workspace build:

devsy workspace build --repository ghcr.io/my-org/my-devcontainer --tag latest --push

Later CI jobs can pass that image to --cache-from.

GitHub Actions

The workflow installs the CLI, sets up the Docker provider, and runs devsy ci:

name: Devcontainer CI
on:
  push:
    branches: [main]
  pull_request:

jobs:
  devcontainer:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Devsy
        run: |
          sudo curl -fsSL https://github.com/devsy-org/devsy/releases/latest/download/devsy-linux-amd64 -o /usr/local/bin/devsy
          sudo chmod +x /usr/local/bin/devsy
      - name: Run CI in devcontainer
        run: |
          devsy provider add docker && devsy provider use docker
          devsy ci -- make test

On this page