SSH Shell access to your GitHub actions VM

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 runner container 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 can 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 helpful 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 over 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.