Action-Debugger

A common pain point that we have come across while using GitHub Actions extensively is the missing ability to debug any action. If the action fails, we have to rely on the logs generated by steps and keep re-running the actions to see if something changes. This leads to the frustrating trial and error way of debugging.

To handle this, we built Action-Debugger. Action-Debugger lets you SSH into a running GitHub Action to debug it. It is as simple as adding a single line to your workflow.

Action-Debugger is a free to use, open-source GitHub action which can be plugged in to any GitHub workflow to make it easy to debug.

Any workflow's execution will get paused as soon as the Action-Debugger step is invoked. While it is paused, an SSH session will be started on the runner machine and the SSH URL will be outputted inside the action logs and as a check in the corresponding GitHub run. Action-Debugger will keep the action paused on the step until a user connects and exits that session.

Below are some additional features of the action that might come in handy while debugging.

Security

By default, if the GitHub user that triggers the action has added SSH keys to their account, then only they would be allowed to connect to the session. Otherwise, anyone on the internet would be able to connect to that session, if they have/guess the generated SSH URL. However, this can be forced as well by setting the option limit-access-to-actor to true.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup interactive ssh session
        uses: Warpbuilds/action-[email protected]
        with:
          limit-access-to-actor: true

Only pause on failure

This will make Action-Debugger pause the workflow execution only when any of the previous steps fail.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup interactive ssh session
        if: ${{ failure() }}
        uses: Warpbuilds/action-[email protected]

Run in detached mode

The default behavior of Action-Debugger is to pause the workflow as it is invoked. The workflow resumes after the SSH session is ended by the user. When setting detached as true, all the steps of the workflow will execute as normal and then the action will be paused at the end of the job.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup interactive ssh session
        uses: Warpbuilds/action-[email protected]
        with:
          detached: true

Timeouts

A custom timeout can be specified to close the SSH session automatically after the specified time. By default, GitHub Actions kills workflows after 6 hours. We recommend setting a default timeout as the runner minutes are billed when the debug session is running. Accidentally leaving an action running might incur unexpected costs.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup interactive ssh session
        uses: Warpbuilds/action-[email protected]
        timeout-minutes: 15

Deterministic SSH URLs (Named sessions)

(This feature requires an API key from WarpBuild. Please contact WarpBuild Support.)

SSH URLs produced by the Action-Debugger are long random strings which are uniquely generated every time an action is run. This is to keep anyone from guessing the string and connecting to the runner machine. However, there can be cases where you want to keep the URL same across action runs. This can be achieved using named sessions.

Just input named-session-name and named-session-api-key, and the action will always generate the SSH URL in the form of <username>/<named-session-name>@gha.warp.build.

Make sure that limit-access-to-actor is set to true for named sessions.

name: CI
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup interactive ssh session
        uses: Warpbuilds/action-[email protected]
        with:
          limit-access-to-actor: true
          named-session-name: random-string-2345ab
          named-session-api-key: <API_KEY_PROVIDED_BY_WARPBUILD>

Troubleshooting

SSH URL is not appearing in checks of my action run

To create a check in the repo, Action-Debugger requires write permission to the checks scope. Please make sure that read and write permissions are enabled in Workflow permissions.

This may need to be set at the organization level instead of the repository level.

More info about these permissions can be found here: GitHub token permissions

I'm seeing a blank screen when I connect to the SSH session

This is likely because of tmux. ctrl+c will drop you into a shell. However, this may disable the multiplexing feature of tmux.

Acknowledgement

This project owes much to the great work done by tmate.io.