SSH Shell Access to your GitHub actions VM

SSH to GitHub Actions

Have you ever had a GitHub action fail and wish you could just quickly log in to the build vm to troubleshoot? Well, good news! That's the topic of today's blog, in which we'll explain how you can enhance your existing GitHub Actions with just a few lines of extra code so that you can get a shell to your actions VM each time it fails.


The need for direct access

GitHub Actions has become an indispensable tool over the last few years, serving as a CI/CD pipeline for many code repositories. Like any codebase, bugs are inevitable. Fortunately, most are caught by integration tests run during the build process. The typical next step is to review the logs to identify the issue. However, sometimes the logs aren't enough, and direct access to the build vm is needed for troubleshooting. Unfortunately, that's not possible with GitHub Actions; today, today we're solving that!

SSH into Your GitHub Actions vm with SSO Credentials

Border0 allows users to access SSH, databases, and web applications without a VPN using their existing Single Sign-On (SSO) credentials. During a recent hackathon, we leveraged this feature to create a GitHub Actions plugin. This will allow users to quickly and easily log in to their GitHub action vm using just their Gmail, Github, or Microsoft SSO credentials.

Now, when your build action fails, you'll receive a notification. You can then use our browser-based WASM SSH client to troubleshoot issues directly on the virtual machine, identify the problem, fix it, and move on.

Integrating Border0 into Your Pipeline

To make things easy, we've made the Border0 action available so that you can easily include it in your existing actions.  Make sure to explore our GitHub repository and explore the README and examples here.

To get started, you'll need a Border0 account  (Register here) and an API token. You can easily add the Border0 GitHub Action as an additional step in your existing workflow, as shown below:

name: CI/CD Pipeline with Border0 GitHub Action on: push: workflow_dispatch: inputs: debug: type: boolean description: Manual trigger required: false default: false jobs: gh-action-job: runs-on: ubuntu-latest steps: - name: A step that will always fail run: | echo "this step will wait 10 seconds and always fails" sleep 10 exit 1 - name: Start Border0 in case of failure. if: failure() uses: borderzero/gh-action@v2 with: token: ${{ secrets.BORDER0_ADMIN_TOKEN }} slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }} wait-for: 20

From now on, the next time your action fails, you'll be able to log into your runner vm.

Failed GitHub Action run, with link to web based SSH shell terminal

Advanced usage 

By default, the Border0 action creates an SSH service only when the action fails. However, you have more options. For instance, you may want the SSH service to run for every workflow run, regardless of its success or failure. An example of that can be found in the README.

Another useful addition is the Slack integration. This will inform you of the failed action and send the SSH url to your Slack workspace.

Slack notification with url to web ssh terminal.

Using Border0 policies, you have complete control of who will have access to your build virtual machine. Not only can you define what SSO identities have access, but you can also configure specific IP addresses and countries and use date & time-based filters. Best of all, you'll get a complete session log, showing you exactly who logged in when, and from where, including a session recording. These recordings can then be replayed and show you exactly what commands were executed and what happened during the session. Great for compliance, troubleshooting, and even training purposes.

Watch back the recording of your troubleshooting session in the Border0 admin portal

Wrap up.

Troubleshooting your GitHub Actions just got a whole lot easier! In this blog we saw how easy it is to add the Border0 Action to your workflow and get a shell to your build vm each time there's a build failure. Sometimes, staring at the logs just isn't enough, and we really want a shell and poke around. This will allow you and the rest of your team to troubleshoot the issue faster and more efficiently.

Users can access their build vm using their existing SSO credentials, protected by the Border0 policies, so it's easy to define who should have access. Users can use their regular SSH client or the Border0 web SSH client, allowing them to quickly troubleshoot even from their tablet or phone!

To try out Border0 GitHub action today, sign up for our free, fully featured community edition and run the example for yourself! Alternatively, schedule a demo and let us walk you through a custom demo.

Ready to level up your security?