action-tmate is a GitHub Action that enables interactive SSH debugging of GitHub Actions workflows by spawning a tmate session on the runner.
The tool solves the problem of opaque workflow failures by giving developers direct shell access to the runner system where their actions execute. When added to a workflow, it creates a tmate session and displays connection details in the GitHub Checks tab, allowing developers to SSH into or access a web-based terminal on the runner. This lets them inspect the environment, run commands interactively, and understand why steps are failing before continuing the workflow.
The action supports Linux, macOS, and Windows runners. Developers should choose this tool when they need to debug workflow failures that are difficult to diagnose from logs alone. It works well for both always-on debugging during development and conditional debugging triggered manually via workflow_dispatch, avoiding the need to commit and push debug steps repeatedly. The detached mode is particularly useful for non-blocking debugging: it starts the tmate session, prints connection details, and continues with subsequent workflow steps rather than pausing execution. In detached mode, the action exposes outputs like ssh-command and web-url that can be used in downstream steps or jobs. The tool also handles edge cases like runners without sudo and allows custom timeout configuration to control GitHub Actions usage.
The project shows consistent maintenance with regular updates addressing user-reported issues and feature requests. Pull requests receive timely review and merge decisions. The codebase demonstrates attention to cross-platform compatibility, with explicit handling for Linux, macOS, and Windows environments. Documentation is actively maintained to reflect available features and usage patterns, including examples for common workflows like manual triggering and detached mode operation.
