Remote debugging Github actions workflow

I was in the process of setting up a new deployment workflow for one of my GitHub repositories. I tested all the scripts locally that I added to the GitHub actions workflow file (.github/workflow/deployment.yml) and to my relief all the scripts worked as expected. On that positive note, I pushed the new workflow file and was waiting eagerly to see the little yellow dots on Github actions turn green

Well, it did turn green but I realized that something was not right after validating the deployed artifacts. (If things go as expected in the first try then our jobs as devs wouldn't be that interesting now, would it ?)

The issue was that the workflow missed to include some required assets in the deployed bundle. The same script which worked locally without any issues was misbehaving in the pipeline, and I spend an hour scrutinizing the yaml file line by line and I could see nothing deviating from what the workflow was intended to do. So I concluded that somehow my setup is not compatible with the worker that GitHub uses to run my workflow.

I was looking for an option to directly get into the worker that is running my workflow so that it would be easier to troubleshoot the bug. I was on the looking spree for a tool that does the same and after a very short time of research, I found the perfectly suitable one

Action: https://github.com/csexton/debugger-action

TL;DR The above action can be included in the workflow yaml file and it will keep the job hanging from the stage where the action was referred. It will print the SSH details to the console which can be used to remotely login to the GitHub worker that is running the workflow

How to set it up?

Setting up this action is very simple. You just need to add the following code to your workflow yaml file and this action will block your job from that stage onwards

- name: Setup Debug Session
  uses: csexton/debugger-action@master

Here is a sample workflow file with the complete setup

name: New Pipeline

on:
  push:
    branches: [ main ]

  pull_request:
    branches: [ main ]

jobs:
  debug-workflow:
    name: Job to debug the workflow
    runs-on: ubuntu-latest
    steps:
      - name: Check out code
        uses: actions/checkout@v2

      - name: Setup Debug Session
        uses: csexton/debugger-action@master

Once the job is blocked, if you expand the details of that stage you will get the details to login remotely to the worker using SSH

If you have a working terminal capable of logging into a remote host using SSH, then just running ssh xxxxxxxxxxxx@sfo2.tmate.io should directly take you to the worker. The default session timeout is set to 15 minutes and if you wish to extend it, then running the command touch /tmp/keepalive should do the trick.

Remote session of the github actions worker

From the SSH session, if you know your way around remote sessions and the commands for your host then you can troubleshoot your issues with ease.

In my case, the issue was due to an improperly configured path relative to the working directory which I found out once I tried to run the commands manually within the worker.

Conclusion

This is such a simple-to-setup action that comes in handy when you are setting up new GitHub actions workflows and if you wish to ensure that the internals are being setup properly (Let's not leave room for any surprises on the day of deployment)