{"id":19147999,"url":"https://github.com/owenthereal/action-upterm","last_synced_at":"2025-12-28T10:18:25.798Z","repository":{"id":238910818,"uuid":"797886005","full_name":"owenthereal/action-upterm","owner":"owenthereal","description":"Enable real-time SSH debugging of GitHub Actions using upterm, providing direct access to the runner system for enhanced troubleshooting and workflow control.","archived":false,"fork":false,"pushed_at":"2025-03-25T21:58:10.000Z","size":699,"stargazers_count":8,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-31T05:41:17.797Z","etag":null,"topics":["actions","debug","debugging","github-action","github-actions","ssh","tmux","upterm"],"latest_commit_sha":null,"homepage":"https://upterm.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/owenthereal.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"lhotari"}},"created_at":"2024-05-08T17:18:44.000Z","updated_at":"2025-03-29T16:35:45.000Z","dependencies_parsed_at":"2024-05-27T21:22:31.840Z","dependency_job_id":"6a86e415-d612-4709-a04e-efd06600ee77","html_url":"https://github.com/owenthereal/action-upterm","commit_stats":null,"previous_names":["owenthereal/action-upterm"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owenthereal%2Faction-upterm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owenthereal%2Faction-upterm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owenthereal%2Faction-upterm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/owenthereal%2Faction-upterm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/owenthereal","download_url":"https://codeload.github.com/owenthereal/action-upterm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249714561,"owners_count":21314868,"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","debug","debugging","github-action","github-actions","ssh","tmux","upterm"],"created_at":"2024-11-09T07:52:54.989Z","updated_at":"2025-12-28T10:18:25.788Z","avatar_url":"https://github.com/owenthereal.png","language":"TypeScript","funding_links":["https://github.com/sponsors/lhotari"],"categories":["JavaScript"],"sub_categories":[],"readme":"# Debug [GitHub Actions](https://github.com/features/actions) With SSH\n\nThis GitHub Action enables direct interaction with the host system running your GitHub Actions via SSH, utilizing [upterm](https://upterm.dev/) and [tmux](https://github.com/tmux/tmux/wiki). This setup facilitates real-time GitHub Actions debugging and allows seamless workflow continuation.\n\n## Features\n\n- **Interactive Debugging**: Gain SSH access to the GitHub Actions runner to diagnose and resolve real-time issues.\n- **Workflow Control**: Resume workflows post-debugging without complete restarts, saving time and preserving state.\n\n## Supported Operating Systems\n\n- **Linux** - Fully supported\n- **macOS** - Fully supported\n- **Windows** - Supported (requires MSYS2, automatically installed on GitHub Actions Windows runners)\n\n## Getting Started\n\nTo set up an `upterm` session within your GitHub Actions workflow, use this example:\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup upterm session\n      uses: owenthereal/action-upterm@v1\n```\n\nAccess the SSH connection string in the `Checks` tab of your Pull Request.\n\n## Use Registered Public SSH Keys\n\nTo enhance security, you can restrict access to the `upterm` session to specific authorized GitHub profiles. First, ensure you have [added an SSH key to your GitHub profile](https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account).\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup upterm session\n      uses: owenthereal/action-upterm@v1\n      with:\n        limit-access-to-actor: true # Restrict to the user who triggered the workflow\n        limit-access-to-users: githubuser1,githubuser2 # Specific authorized users only\n```\n\nIf your registered public SSH key differs from your default private SSH key, specify the path manually: `ssh -i \u003cpath-to-private-key\u003e \u003cupterm-connection-string\u003e`.\n\n## Use Custom Upterm Server\n\nTo host your own Upterm server, follow the instructions for [deployment across various cloud providers](https://github.com/owenthereal/upterm?tab=readme-ov-file#hammer_and_wrench-deployment).\nConfigure the Upterm server with the `upterm-server` input parameter:\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup upterm session\n      uses: owenthereal/action-upterm@v1\n      with:\n        ## Use the deployed Upterm server via Websocket or SSH\n        upterm-server: wss://YOUR_HEROKU_APP_URL\n```\n\n## Pin a Specific Upterm Version\n\nBy default, the action downloads the latest Upterm release directly from GitHub. To pin a specific release (for example, `v0.20.0`), provide the optional `upterm-version` input:\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup upterm session\n      uses: owenthereal/action-upterm@v1\n      with:\n        upterm-version: v0.20.0\n```\n\n- Works on all platforms (Linux, macOS, and Windows).\n- On macOS, Upterm is installed from the GitHub release tarball (Homebrew is still used for installing `tmux` only).\n\n## Shut Down the Server if No User Connects\n\nIf no user connects, the server automatically shuts down after a specified time. This feature is handy for deploying `action-upterm` to provide a debug shell on job failure without unnecessarily prolonging pipeline operation.\n\n```yaml\nname: CI\non: [push]\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v2\n    - name: Setup upterm session\n      uses: owenthereal/action-upterm@v1\n      if: ${{ failure() }}\n      with:\n        ## Shut down the server if unconnected after 5 minutes.\n        wait-timeout-minutes: 5\n```\n\n## Continue a Workflow\n\nTo resume your workflow within an `upterm` session, create a file named `continue` in one of these locations:\n\n```bash\n# In the workflow workspace (recommended, no sudo required)\ncd $GITHUB_WORKSPACE \u0026\u0026 touch continue\n\n# Or at the filesystem root (may require sudo)\nsudo touch /continue\n```\n\nPress `C-b` followed by `d` (tmux detach command keys) to detach from the terminal without resuming the workflow.\n\n## Usage Tips\n\n### Resizing the tmux Window\n\nAfter connecting via SSH:\n\n- Press `control-b`, then type `:resize-window -A` and press `\u003center\u003e`\n\nThis will resize the console to the full width and height of the connected terminal.\n([Learn more](https://unix.stackexchange.com/a/570015))\n\n### Windows Support\n\nWindows runners are fully supported through MSYS2 (pre-installed on GitHub Actions Windows runners). The action automatically:\n- Downloads the Windows build of upterm\n- Installs tmux via pacman (MSYS2 package manager)\n- Handles Windows/POSIX path format conversions internally\n\n**Continue file locations on Windows:**\n```bash\n# In the workflow workspace (recommended, no sudo/admin required)\ncd $GITHUB_WORKSPACE \u0026\u0026 touch continue\n\n# Or at the MSYS2 root (may require elevation)\ntouch /c/msys64/continue\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowenthereal%2Faction-upterm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowenthereal%2Faction-upterm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowenthereal%2Faction-upterm/lists"}