This GitHub Action offers you a direct way to interact with the host system on which the actual scripts (Actions) will run.

• Debug your GitHub Actions by using SSH or Web shell
• Continue your Workflows afterwards

• Linux
• macOS
• Windows

By using this minimal example a tmate session will be created.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3

To get the connection string, just open the Checks tab in your Pull Request and scroll to the bottom. There you can connect either directly per SSH or via a web based terminal.

Instead of having to add/remove, or uncomment the required config and push commits each time you want to run your workflow with debug, you can make the debug step conditional on an optional parameter that you provide through a workflow_dispatch "manual event".

Add the following to the on events of your workflow:

on:
  workflow_dispatch:
    inputs:
      debug_enabled:
        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'     
        required: false
        default: false

Then add an if condition to the debug step:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # Enable tmate debugging of manually-triggered workflows if the input option was provided
      - name: Setup tmate session
        uses: mxschmitt/action-tmate@v3
        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled }}

You can then manually run a workflow on the desired branch and set debug_enabled to true to get a debug session.

By default we run the commands using sudo. If you get sudo: not found you can use the parameter below to execute the commands directly.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3
      with:
        sudo: false

By default the tmate session will remain open until the workflow times out. You can specify your own timeout in minutes if you wish to reduce GitHub Actions usage.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3
      timeout-minutes: 15

By default a failed step will cause all following steps to be skipped. You can specify that the tmate session only starts if a previous step failed.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup tmate session
      if: ${{ failure() }}
      uses: mxschmitt/action-tmate@v3

By default anybody can connect to the tmate session. You can opt-in to install the public SSH keys that you have registered with your GitHub profile.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3
      with:
        limit-access-to-actor: true

If the registered public SSH key is not your default private SSH key, you will need to specify the path manually, like so: ssh -i <path-to-key> <tmate-connection-string>.

If you want to continue a workflow and you are inside a tmate session, just create a empty file with the name continue either in the root directory or in the project directory by running touch continue or sudo touch /continue.

The connection string will be written in the logs every 5 seconds. For more information checkout issue #1.