Devsy
Developing in a Workspace

Continuous Integration

devsy ci starts a devcontainer workspace and runs a command in it. Use it to run tests inside the container and check the build of a newly created workspace.

If you omit the workspace argument and select an existing workspace interactively, Devsy can delete that workspace after the run, including its workspace data. Pass --keep when selecting a workspace interactively to prevent cleanup.

How it works

  1. Devsy resolves a workspace from the given source. With no source, it prompts for a workspace in an interactive terminal.
  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. Unless you pass --keep, Devsy attempts cleanup when its initial lookup finds no existing workspace, even when the command fails. This can delete an existing workspace selected interactively after that lookup.

A failing command fails the CI job. Workspace setup or cleanup errors also cause devsy ci to fail.

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 keeps the build and lifecycle hook history in the local store after workspace cleanup. 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.

Hooks cannot ask for input

CI jobs have no terminal to answer a prompt. devsy ci has no --interactive-post-start option. Write hooks that take their values from the job instead.

Desktop launches, --detach, JSON output, and management or platform tasks also stay noninteractive. If you pass --interactive-post-start to devsy workspace up in one of these runs, Devsy rejects it with an error. It does not wait for input that nobody can see.

Pass values to the workspace in one of these ways:

  • Environment variables: devsy ci --workspace-env NAME=value . -- make test. Use --workspace-env for values that hooks need. The --remote-env flag applies only to the command that CI runs.
  • Secrets: --secret injects a stored Devsy secret. See Secrets.
  • Files: write the value to a file that the hook reads.
  • Arguments: put a value that is not secret in the hook command, such as "postStartCommand": ["./start.sh", "example-name"].

Moving the prompt to postAttachCommand does not provide input. postAttachCommand runs without input in every mode.

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