Repository files navigation

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 atmate session will be created.

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3

To get the connection string, just open theChecks 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 aworkflow_dispatch "manual event".

Add the following to theon events of your workflow:

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

Then add anif condition to the debug step:

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

You can thenmanually run a workflow on the desired branch and setdebug_enabled to true to get a debug session.

By default, this Action starts atmate session and waits for the session to be done (typically by way of a user connecting and exiting the shell after debugging). In detached mode, this Action will start thetmate session, print the connection details, and continue with the next step(s) of the workflow's job. At the end of the job, the Action will wait for the session to exit.

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3with:detached:true

By default, this mode will wait at the end of the job for a user to connect and then to terminate the tmate session. If no user has connected within 10 minutes after the post-job step started, it will terminate thetmate session and quit gracefully.

As this mode has turned out to be so useful as to having the potential for being the default mode once time travel becomes available, it is also available asmxschmitt/action-tmate/detached for convenience.

When running in detached mode, the action sets the following outputs that can be used in subsequent steps or jobs:

• ssh-command: The SSH command to connect to the tmate session
• ssh-address: The raw SSH address without the "ssh" prefix
• web-url: The web URL to connect to the tmate session (if available)

Example workflow using the SSH command in another job:

name:Debug with tmateon:[push]jobs:setup-tmate:runs-on:ubuntu-latestoutputs:ssh-command:${{ steps.tmate.outputs.ssh-command }}ssh-address:${{ steps.tmate.outputs.ssh-address }}steps:    -uses:actions/checkout@v4    -name:Setup tmate sessionid:tmateuses:mxschmitt/action-tmate@v3with:detached:trueuse-ssh-command:needs:setup-tmateruns-on:ubuntu-lateststeps:    -name:Display SSH commandrun:|        # Send a Slack message to someone telling them they can ssh to ${{ needs.setup-tmate.outputs.ssh-address }}

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

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3with:sudo:false

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

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3timeout-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 stepfailed.

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionif:${{ failure() }}uses:mxschmitt/action-tmate@v3

Ifyou have registered one or more public SSH keys with your GitHub profile, tmate will be started such that only those keys are authorized to connect, otherwise anybody can connect to the tmate session. If you want to require a public SSH key to be installed with the tmate session, no matter whether the user who started the workflow has registered any in their GitHub profile, you will need to configure the settinglimit-access-to-actor totrue, like so:

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3with: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>.

By default the tmate session usesssh.tmate.io. You can use your own tmate servers.tmate-ssh-server is the server side part of tmate.

name:CIon:[push]jobs:build:runs-on:ubuntu-lateststeps:    -uses:actions/checkout@v4    -name:Setup tmate sessionuses:mxschmitt/action-tmate@v3with:tmate-server-host:ssh.tmate.iotmate-server-port:22tmate-server-rsa-fingerprint:SHA256:Hthk2T/M/Ivqfk1YYUn5ijC2Att3+UPzD7Rn72P5VWstmate-server-ed25519-fingerprint:SHA256:jfttvoypkHiQYUqUCwKeqd9d1fJj/ZiQlFOHVl6E9sI

By default, tmate and its dependencies are installed in a platform-dependent manner. When using self-hosted agents, this can become unnecessary or can even break. You can skip installing tmate and its dependencies usinginstall-dependencies:

name:CIon:[push]jobs:build:runs-on:[self-hosted, linux]steps:    -uses:mxschmitt/action-tmate@v3with:install-dependencies:false

If you want to integrate with the msys2/setup-msys2 action or otherwise don't have an MSYS2 installation atC:\msys64, you can specify a different location for MSYS2:

name:CIon:[push]jobs:build:runs-on:windows-lateststeps:    -uses:msys2/setup-msys2@v2id:setup-msys2    -uses:mxschmitt/action-tmate@v3with:msys2-location:${{ steps.setup-msys2.outputs.msys2-location }}

If you want to continue a workflow and you are inside a tmate session, just create a empty file with the namecontinue either in the root directory or in the project directory by runningtouch continue orsudo touch /continue (on Linux).

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