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 to the deployed bundle. The same script which worked locally without any issues was mis-behaving 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 came to the conclusion 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 exactly 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 to 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 setup?

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 Pipelineon:  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 [email protected] (masked the actual username with xxx for security) should directly take you into 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 which 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)