Can I SSH into a CI runner to debug a failed build?

Yes, as long as the CI runner is still running.

With Depot CI, you can attach to a live job over SSH or rerun the job with an SSH session inserted after a specific step. That gives you a shell on the actual machine where the failure happens. You can inspect the filesystem, check environment variables, rerun commands, and stop guessing from logs.

You cannot SSH into a runner after its job has finished and the machine has been destroyed. CI runners are usually ephemeral. For a completed failure, rerun the job and pause it before the failing step.

SSH into a running Depot CI job

Use depot ci ssh to attach to a job that is currently running:

depot ci ssh <run-id> --job <job>

If the run contains one job, you can omit --job:

depot ci ssh <run-id>

You can also pass the job ID directly:

depot ci ssh <job-id>

If the job is still queued, the command waits up to five minutes for its sandbox to start. Once connected, you are the runner user with root privileges inside the sandbox.

This is useful when a job is hung, a command is still running, or you want to inspect the sandbox before the workflow has completed. Direct SSH connects to the sandbox itself. It does not guarantee that the workflow has already checked out the repository, installed dependencies, or populated its environment.

Pause immediately before the failure

For a job that has already failed, the more useful option is usually --ssh-after-step.

Rerun one job and tell Depot CI to insert an SSH debug session after the last successful step:

depot ci run \
  --workflow .depot/workflows/ci.yml \
  --job test \
  --ssh-after-step 3

Depot CI runs the first three steps, pauses the workflow, and connects your terminal to the runner through tmate. The checked-out code, installed dependencies, files, and environment variables from those steps are still there.

That is the useful bit. You are looking at the same state the failing command sees.

If step four runs pnpm test, you can run it manually. If it expects an artifact, use ls and find out whether the artifact exists. If a variable looks wrong, inspect it. The machine can answer questions that the logs cannot.

Exit the session with exit or CTRL-D. The workflow will continue with the remaining steps.

Start a new job inside an SSH session

Use --ssh when you want a shell as soon as a new sandbox is ready:

depot ci run \
  --workflow .depot/workflows/ci.yml \
  --job test \
  --ssh

This opens the raw sandbox before you reach a particular workflow step. Use --ssh-after-step instead when the failure depends on state created by earlier steps.

Both flags require exactly one --job. They cannot be used together.

SSH debugging on Depot-hosted GitHub Actions runners

Depot-hosted GitHub Actions runners are compatible with mxschmitt/action-tmate. Add it as a step before the command you need to debug:

- name: Open SSH session
  uses: mxschmitt/action-tmate@v3

- name: Run tests
  run: pnpm test

When the workflow reaches the tmate step, its logs contain an SSH command and a browser terminal link. The job remains paused while you inspect it. Exit the session to let the workflow continue.

Depot does not maintain action-tmate. Depot CI's --ssh-after-step option injects the same kind of pause for you, so you do not have to edit the workflow first.

A practical debugging loop

Start with the cheapest source of information, then move closer to the machine:

1. Read the failed step's logs.
2. Identify the last step that completed successfully.
3. Rerun only the failed job with --ssh-after-step set to that step number.
4. Inspect the working directory, files, environment, processes, and network from inside the runner.
5. Run the failing command manually.
6. Fix the problem locally and rerun the job.

For the full command reference and security considerations, see Debug a failing job with SSH.