GitHub Actions Online Debugging Tool: debugger-action

1. Debugging Until You Want to Quit

GitHub Actions is the continuous integration service GitHub launched in October 2018. For open-source projects it offers unlimited free build time, and it supports Linux, MacOs, and Windows systems, which makes it very appealing.

But a recent experience changed my view. I submitted a commit, improvement: build and ci, to a colleague’s repository, to improve its continuous build setup. As shown below:

These are just a few entries from the debugging process. It passed locally, but as soon as I added it to the workflows it failed. I spent more than a day on it, submitting no fewer than dozens of commits for testing. This was a private repository, so I had to follow the Merge Requests development process. That in itself was fine — the problem was that my boss was watching the repository. Every failed build sent him a notification email, and it happened right at the end of the year. Tears ~~~

2. The Birth of debugger-action

That weekend I happened to see that PingCap was running a Hackathon, a chance to focus on completing one feature in a short time. Inspiration struck, and I spent the weekend using GitHub Actions to solve the problem of debugging until you want to quit.

I skimmed TypeScript syntax, leaned on a bit of my earlier SaaS full-stack development background and the power of Google search, and got it done.

Let’s look together at how to debug GitHub Actions. Below is a Go workflows environment:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
name: Build

on:
  push:
    branches: [master]

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Set up Go 1.14
        uses: actions/setup-go@v1
        with:
          go-version: 1.14

      - name: Check out code into the Go module directory
        uses: actions/checkout@v2

      - uses: shaowenchen/debugger-action@v1
        name: debugger
        timeout-minutes: 30
        continue-on-error: true
        with:
          frp_server_addr: ${{ secrets.FRP_SERVER_ADDR }}
          frp_server_port: ${{ secrets.FRP_SERVER_PORT }}
          frp_token: ${{ secrets.FRP_TOKEN }}
          ssh_port: ${{ secrets.SSH_PORT }}

Once it is running, the Runner is held for 30 minutes, and the developer can log in to the Runner remotely over ssh to run commands and debug.

1
ssh root@frp_server_addr -p ssh_port

Enter the root password: root

That gets you into the Runner’s execution environment. debugger-actions currently supports Linux and MacOS build environments.

3. Configuring and Using debugger-action

3.1 Setting Up the Frp Server

See a post I wrote earlier, Using frp to Publish a Local Service to the Public Network, which includes a one-click install script.

A successful install yields a configuration:

==============================================
You Server IP      : x.x.x.x
Bind port          : 5443
KCP support        : true
vhost http port    : 80
vhost https port   : 443
Dashboard port     : 6443
token              : x
tcp_mux            : true
Max Pool count     : 200
Log level          : info
Log max days       : 30
Log file           : enable
==============================================

If you don’t have a server, you can also use the test Frp Server I provide in the project issues, https://github.com/shaowenchen/debugger-action/issues/3 .

3.2 Configuring Secrets

On the Settings page, under Secrets, add three secrets, FRP_SERVER_ADDR, FRP_SERVER_PORT, FRP_TOKEN, with values taken from the previous step. As shown below:

Secrets	Corresponding Frp value
`FRP_SERVER_ADDR`	You Server IP
`FRP_SERVER_PORT`	Bind port
`FRP_TOKEN`	token

SSH_PORT can be set to anything, but it must not be the same across different Workflows. If SSH_PORT is the same, the Frp Client will fail to start. You can of course use a fixed value, it is just less secure.

3.3 Adding debugger-action

Add the following yaml snippet wherever you need to Debug in your Workflows.

1
2
3
4
5
6
7
8
9
- uses: shaowenchen/debugger-action@v1
  name: debugger
  timeout-minutes: 30
  continue-on-error: true
  with:
    frp_server_addr: ${{ secrets.FRP_SERVER_ADDR }}
    frp_server_port: ${{ secrets.FRP_SERVER_PORT }}
    frp_token: ${{ secrets.FRP_TOKEN }}
    ssh_port: ${{ secrets.SSH_PORT }}

Here timeout-minutes sets how long you need to Debug for. In GitHub Actions, the maximum execution time allowed for each Job is 6 hours.

4. Trying It Out

Use the ssh command, root/root (account/password), to log in to the Runner.

1
ssh root@frp_server_addr -p ssh_port

You can also see the connection in the Frp Dashboard.

5. Some Test Cases

5.1 A buildx Build Environment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
name: buildx
on:
  push:
    branches: [master]

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      - uses: shaowenchen/debugger-action@v1
        name: debugger
        timeout-minutes: 30
        continue-on-error: true
        with:
          frp_server_addr: ${{ secrets.FRP_SERVER_ADDR }}
          frp_server_port: ${{ secrets.FRP_SERVER_PORT }}
          frp_token: ${{ secrets.FRP_TOKEN }}
          ssh_port: 29001

Command-line test:

1
2
3
4
docker ps

CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS              PORTS               NAMES
94e481a9d5a5        moby/buildkit:buildx-stable-1   "buildkitd --allow-i…"   23 minutes ago      Up 23 minutes                           buildx_buildkit_builder-1cfe11cc-90d5-4518-9d89-a05765ac30620

5.2 A Kind Cluster

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
name: kind
on:
  push:
    branches: [master]

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: Creating kind cluster
        uses: helm/kind-action@v1.0.0-rc.1
      - uses: shaowenchen/debugger-action@v1
        name: debugger
        timeout-minutes: 30
        continue-on-error: true
        with:
          frp_server_addr: ${{ secrets.FRP_SERVER_ADDR }}
          frp_server_port: ${{ secrets.FRP_SERVER_PORT }}
          frp_token: ${{ secrets.FRP_TOKEN }}
          ssh_port: 29002

Command-line test:

1
2
3
4
kubectl get node

NAME                          STATUS   ROLES    AGE   VERSION
chart-testing-control-plane   Ready    master   24m   v1.17.0

5.3 A MacOS Environment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
name: macos-shell
on:
  push:
    branches: [master]

jobs:
  hello:
    runs-on: macos-latest
    steps:
      - uses: shaowenchen/debugger-action@v1
        name: debugger
        timeout-minutes: 30
        continue-on-error: true
        with:
          frp_server_addr: ${{ secrets.FRP_SERVER_ADDR }}
          frp_server_port: ${{ secrets.FRP_SERVER_PORT }}
          frp_token: ${{ secrets.FRP_TOKEN }}
          ssh_port: 29003

Command-line test:

1
2
3
Mac-1610933038460:~ runner$ uname -a

Darwin Mac-1610933038460.local 19.6.0 Darwin Kernel Version 19.6.0: Thu Oct 29 22:56:45 PDT 2020; root:xnu-6153.141.2.2~1/RELEASE_X86_64 x86_64