Open a debugging shell in GitHub Actions with tmate#

:warning: 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 https://tmate.io/ 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:

1
name: tmate session
2

3
on:
4
  workflow_dispatch:
5

6
jobs:
7
  build:
8
    runs-on: ubuntu-latest
9
    steps:
10
    - uses: actions/checkout@v2
11
    - name: Setup tmate session
12
      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:

1
WebURL: https://tmate.io/t/JA69KaB2avRPRZSkRb8JPa9Gd
2

3
SSH: ssh JA69KaB2avRPRZSkRb8JPa9Gd@nyc1.tmate.io

I ran ssh JA69KaB2avRPRZSkRb8JPa9Gd@nyc1.tmate.io 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.

1
    steps:
2
    - name: Run tests
3
      run: pytest
4
    - name: tmate session if tests fail
5
      if: failure() && github.event_name == 'workflow_dispatch'
6
      uses: mxschmitt/action-tmate@v3