Skip to main content

SSH into a GitHub Actions runner

Follow this page to open a shell on the runner of a test job, so you can debug a failure on the machine where it happened. It's for maintainers with write access to the repository and an SSH client.

The Test PHP, Test Node.js, Test shell and Test Docker workflows end each test job with a Setup upterm session step. The step uses the owenthereal/action-upterm action, which shares the runner's terminal over SSH through the public upterm server at uptermd.upterm.dev. GitHub runs the step only on a run you start by hand with the Enable terminal session. checkbox selected. It runs last, even when an earlier step fails.

The step admits only the GitHub user who started the run, or who re-ran the job. Before you start, add an SSH key to your GitHub account.

To open an SSH session on a runner:

  1. In your repository on GitHub, click Actions.

  2. Select the workflow to debug, such as Test PHP.

  3. Click Run workflow to open the run options.

  4. Select the Enable terminal session. checkbox.

  5. In the run options, click the green Run workflow button.

  6. Click the new run.

  7. Click the job to debug. The Setup upterm session step prints an SSH command like this one in the job log:

    SSH: ssh [email protected]

  8. In your terminal, run the ssh command from the log. If the key on your GitHub account isn't your default SSH key, add -i and the path to its private key.

To end the session and let the job finish, type exit in the shell. The session also ends 30 minutes after GitHub starts the step.