Open a debugging shell in GitHub Actions with tmate

⚠️ 17 Feb 2022: There have been reports of running tmate causing account suspensions. See this issue for details. Continue with caution.

23 Sep 2023: I've been using this trick very occasionally for nearly two years now without negative consequences.

Thanks to this Twitter conversation I found out about mxschmitt/action-tmate, which uses to open an interactive shell session running inside the GitHub Actions environment.

I created a .github/workflows/tmate.yml file in my repo containing the following:

name: tmate session


    runs-on: ubuntu-latest
    - uses: actions/checkout@v2
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3

Clicking the "Run workflow" button in the GitHub Actions interface then gave me the following in the GitHub Actions log output:


SSH: ssh

I ran ssh and got a direction connection to the Action, with my project files all available thanks to the - uses: actions/checkout@v2 step.

Once I'd finish testing things out in that environment, I typed touch continue and the session ended itself.

Starting a shell just for test failures on manual runs

I had a tricky test failure that I wanted to debug interactively. Here's a recipe for starting a tmate shell ONLY if the previous step failed, and only if the run was triggered manually (using workflow_dispatch) - because I don't want an accidental test opening up a shell and burning up my GitHub Actions minutes allowance.

    - name: Run tests
      run: pytest
    - name: tmate session if tests fail
      if: failure() && github.event_name == 'workflow_dispatch'
      uses: mxschmitt/action-tmate@v3

Created 2020-09-14T15:25:36-07:00, updated 2023-09-23T07:53:52-07:00 · History · Edit