This GitHub Action enables direct interaction with the host system running your GitHub Actions via SSH, utilizing upterm and tmux. This setup facilitates real-time GitHub Actions debugging and allows seamless workflow continuation.

• Interactive Debugging: Gain SSH access to the GitHub Actions runner to diagnose and resolve real-time issues.
• Workflow Control: Resume workflows post-debugging without complete restarts, saving time and preserving state.

• Linux
• macOS
• Windows: Unsupported (actions will skip to avoid pipeline failures).

To set up an upterm session within your GitHub Actions workflow, use this example:

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup upterm session
      uses: owenthereal/action-upterm@main

Access the SSH connection string in the Checks tab of your Pull Request.

To 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.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup upterm session
      uses: owenthereal/action-upterm@main
      with:
        limit-access-to-actor: true # Restrict to the user who triggered the workflow
        limit-access-to-users: githubuser1,githubuser2 # Specific authorized users only

If your registered public SSH key differs from your default private SSH key, specify the path manually: ssh -i <path-to-private-key> <upterm-connection-string>.

To host your own Upterm server, follow the instructions for deployment across various cloud providers. Configure the Upterm server with the upterm-server input parameter:

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup upterm session
      uses: owenthereal/action-upterm@main
      with:
        ## Use the deployed Upterm server via Websocket or SSH
        upterm-server: wss://YOUR_HEROKU_APP_URL

If 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.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Setup upterm session
      uses: owenthereal/action-upterm@main
      if: ${{ failure() }}
      with:
        ## Shut down the server if unconnected after 5 minutes.
        wait-timeout-minutes: 5

To resume your workflow within an upterm session, create an empty file named continue:

touch continue
# or
sudo touch /continue

Press C-b followed by d (tmux detach command keys) to detach from the terminal without resuming the workflow.

After connecting via SSH:

• Press control-b, then type :resize-window -A and press <enter>

This will resize the console to the full width and height of the connected terminal. (Learn more)