{"id":13464468,"url":"https://github.com/mxschmitt/action-tmate","last_synced_at":"2025-05-14T04:08:08.745Z","repository":{"id":38361884,"uuid":"203994683","full_name":"mxschmitt/action-tmate","owner":"mxschmitt","description":"Debug your GitHub Actions via SSH by using tmate to get access to the runner system itself.","archived":false,"fork":false,"pushed_at":"2025-05-03T06:34:25.000Z","size":1042,"stargazers_count":3162,"open_issues_count":31,"forks_count":306,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-05-09T10:41:55.780Z","etag":null,"topics":["actions","debugging","github-action","github-actions","hacktoberfest","ssh","tmate"],"latest_commit_sha":null,"homepage":"https://mxschmitt.github.io/action-tmate/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mxschmitt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"mxschmitt"}},"created_at":"2019-08-23T12:31:19.000Z","updated_at":"2025-05-09T07:40:11.000Z","dependencies_parsed_at":"2024-04-15T08:39:42.774Z","dependency_job_id":"68722cfb-475a-47a1-aea1-4398e84ce441","html_url":"https://github.com/mxschmitt/action-tmate","commit_stats":{"total_commits":109,"total_committers":24,"mean_commits":4.541666666666667,"dds":0.5963302752293578,"last_synced_commit":"e5c7151931ca95bad1c6f4190c730ecf8c7dde48"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":"actions/typescript-action","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxschmitt%2Faction-tmate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxschmitt%2Faction-tmate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxschmitt%2Faction-tmate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mxschmitt%2Faction-tmate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mxschmitt","download_url":"https://codeload.github.com/mxschmitt/action-tmate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254069590,"owners_count":22009558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","debugging","github-action","github-actions","hacktoberfest","ssh","tmate"],"created_at":"2024-07-31T14:00:43.722Z","updated_at":"2025-05-14T04:08:03.724Z","avatar_url":"https://github.com/mxschmitt.png","language":"JavaScript","funding_links":["https://github.com/sponsors/mxschmitt"],"categories":["References","JavaScript","Development Environment","Community Resources"],"sub_categories":["Install Nektos Act on Ubuntu Jammy","Debugging and Tracing","Utility"],"readme":"# Debug your [GitHub Actions](https://github.com/features/actions) by using [tmate](https://tmate.io)\n\n[![GitHub Actions](https://github.com/mxschmitt/action-tmate/workflows/Node.js%20CI/badge.svg)](https://github.com/mxschmitt/action-tmate/actions)\n[![GitHub Marketplace](https://img.shields.io/badge/GitHub-Marketplace-green)](https://github.com/marketplace/actions/debugging-with-tmate)\n\nThis GitHub Action offers you a direct way to interact with the host system on which the actual scripts (Actions) will run.\n\n## Features\n\n- Debug your GitHub Actions by using SSH or Web shell\n- Continue your Workflows afterwards\n\n## Supported Operating Systems\n\n- Linux\n- macOS\n- Windows\n\n## Getting Started\n\nBy using this minimal example a [tmate](https://tmate.io) session will be created.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n```\n\nTo 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.\n\n![GitHub Checks tab](./docs/checks-tab.png \"GitHub Checks tab\")\n\n## Manually triggered debug\n\nInstead 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`](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#workflow_dispatch) \"manual event\".\n\nAdd the following to the `on` events of your workflow:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      debug_enabled:\n        type: boolean\n        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'\n        required: false\n        default: false\n```\n\nThen add an [`if`](https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions) condition to the debug step:\n\n\u003c!--\n{% raw %}\n--\u003e\n```yaml\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      # Enable tmate debugging of manually-triggered workflows if the input option was provided\n      - name: Setup tmate session\n        uses: mxschmitt/action-tmate@v3\n        if: ${{ github.event_name == 'workflow_dispatch' \u0026\u0026 inputs.debug_enabled }}\n```\n\u003c!--\n{% endraw %}\n--\u003e\n\nYou can then [manually run a workflow](https://docs.github.com/en/actions/managing-workflow-runs/manually-running-a-workflow) on the desired branch and set `debug_enabled` to true to get a debug session.\n\n## Detached mode\n\nBy default, this Action starts a `tmate` 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 the `tmate` 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.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n      with:\n        detached: true\n```\n\nBy 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 the `tmate` session and quit gracefully.\n\n## Without sudo\n\nBy default we run installation commands using sudo on Linux. If you get `sudo: not found` you can use the parameter below to execute the commands directly.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n      with:\n        sudo: false\n```\n\n## Timeout\n\nBy default the tmate session will remain open until the workflow times out. You can [specify your own timeout](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions#jobsjob_idstepstimeout-minutes) in minutes if you wish to reduce GitHub Actions usage.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n      timeout-minutes: 15\n```\n\n## Only on failure\nBy 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](https://docs.github.com/en/actions/learn-github-actions/expressions#failure).\n\n\u003c!--\n{% raw %}\n--\u003e\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      if: ${{ failure() }}\n      uses: mxschmitt/action-tmate@v3\n```\n\u003c!--\n{% endraw %}\n--\u003e\n\n## Use registered public SSH key(s)\n\nIf [you have registered one or more public SSH keys with your GitHub profile](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account), 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 setting `limit-access-to-actor` to `true`, like so:\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n      with:\n        limit-access-to-actor: true\n```\n\nIf the registered public SSH key is not your default private SSH key, you will need to specify the path manually, like so: `ssh -i \u003cpath-to-key\u003e \u003ctmate-connection-string\u003e`.\n\n## Use your own tmate servers\n\nBy default the tmate session uses `ssh.tmate.io`. You can use your own tmate servers. [tmate-ssh-server](https://github.com/tmate-io/tmate-ssh-server) is the server side part of tmate.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v4\n    - name: Setup tmate session\n      uses: mxschmitt/action-tmate@v3\n      with:\n        tmate-server-host: ssh.tmate.io\n        tmate-server-port: 22\n        tmate-server-rsa-fingerprint: SHA256:Hthk2T/M/Ivqfk1YYUn5ijC2Att3+UPzD7Rn72P5VWs\n        tmate-server-ed25519-fingerprint: SHA256:jfttvoypkHiQYUqUCwKeqd9d1fJj/ZiQlFOHVl6E9sI\n```\n\n## Skip installing tmate\n\nBy 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 using `install-dependencies`:\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: [self-hosted, linux]\n    steps:\n    - uses: mxschmitt/action-tmate@v3\n      with:\n        install-dependencies: false\n```\n\n## Continue a workflow\n\nIf 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` (on Linux).\n\n## Connection string / URL is not visible\n\nThe connection string will be written in the logs every 5 seconds. For more information checkout issue [#1](https://github.com/mxschmitt/action-tmate/issues/1).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxschmitt%2Faction-tmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmxschmitt%2Faction-tmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmxschmitt%2Faction-tmate/lists"}