Open a terminal into your GitHub Actions workflow

#github-actions-terminal.md

You can use WeTTY to create a web based interactive terminal for a shell running in the context of your GitHub Actions workflow, and combine that with Microsoft dev tunnels to open a secure and authenticated connection into that shell. The default dev tunnels security model secures access by requiring authentication with the same account used to host the tunnel (in the below example a GitHub account).

You can use this to investigate issues with your workflow scripts in the context of the actual runner. Here is an example of htop running on a GitHub hosted agent.

The below workflow step:

1. Installs Dev tunnels and WeTTY (due to a know issue we install version 2.5).
2. Starts WeTTY to host a bash shell over a web interface.
3. Authenticates dev tunnels with your GitHub account. You will need to copy the authentication code and open the GitHub device authentication link to authenticate the dev tunnel client and secure the tunnel to be hosted.
4. Publishes the locally hosted bash shell over dev tunnels. The tunnel access is authenticated with your GitHub account from the previous step. You can open the tunnel from the forwarding link (choose the link on default HTTPS 443) which will take you to an anti-phishing confirmation page followed by GitHub authentication before opening the web terminal.

jobs:
  github-actions-terminal:
    runs-on: ubuntu-24.04
    timeout-minutes: 10
    steps:
      - run: |
          wget -qO /usr/local/bin/devtunnel https://aka.ms/TunnelsCliDownload/linux-x64 && chmod +x /usr/local/bin/devtunnel
          npm -g i [email protected]
          sudo wetty -c bash -b / &
          devtunnel user login -g -d
          devtunnel host -p 3000

Warning

The published shell has access to the workflow execution context including any checked out files as well as environment variables and potentially GITHUB_TOKEN. Review potential impact of a compromised runner to better understand the security implications. In practice the dev tunnel is secured to your Microsoft / GitHub account and should therefore be relatively secure.

Important

The devtunnel host command will block the workflow step indefinately, which might consume your GitHub Actions minutes. The example above uses timeout-minutes to limit the run duration to 10 minutes.