GitHub Actions 的 Runner Images 包含了很多常用的开发环境, 使用它来构建一些软件是很方便的.

不过, 构建过程难免会遇到问题, 而在 GitHub Actions 上进行构建和在本地有很多不同之处.

• 首先 Runner 上的环境复杂, 在本地不易复现, 若是调用了一些外部 Action, 甚至是平台限定的 Action (比如 cache), 就更难处理了;
• 此外, 整个构建的过程一般来说只能通过编辑 Workflow 的配置文件来修改, 一次运行只能等到工作流执行完毕或者遇到错误而终止, 而不能随心所欲地在过程中执行某些命令观察输出或者影响构建过程; 同时, 能够从外部观察到的, 可以作为参考的, 只有工作流的日志输出, 若是遇到莫名其妙的问题, 单凭日志就很难定位到问题所在.

为此, 我们可能希望能在构建过程中的某处 “暂停” 工作流, 并且能够进入机器详细地观察构建的状态.

可行性

GitHub Actions 的 Runner 具有网络访问性, 并且没有特殊的限制, 因此连接到 Runner 上的想法理论上是成立的.

这里我们使用 Cloudflare 的 Zero Trust 来帮助我们访问到 Runner 机器上的 SSH 服务. 运行 cloudflared 的机器会自动连接到 Cloudflare 的边缘节点, 从而能够代理出机器上的服务, 供用户访问.

要使用 Zero Trust 需要先在 Cloudflare 注册账户, 这里不对此进行展开.

准备 Workflow 文件

首先, 为了方便调试, 我们将设置一个 workflow_dispatch 的触发条件, 这样就可以在 Actions 里手动触发多次 Workflow 了.

安装并配置 SSH Server

其次, 我们需要为 Runner 安装 OpenSSH Server (假设使用的是 Ubuntu):

sudo apt update && sudo apt install -qy openssh-server

并且设置 SSH 的访问权限 (修改 /etc/ssh/sshd_config):

PasswordAuthentication no
ChallengeResponseAuthentication no
Match Address 127.0.0.1
    PasswordAuthentication yes
    PermitRootLogin yes

重新装载 sshd.service:

sudo systemctl daemon-reload
sudo systemctl restart sshd --now

以及安装 SSH 公钥 (从 GitHub 拉取自己的 SSH 公钥), 并且确保 ~/.ssh 和 ~/.ssh/authorized_keys 的权限:

mkdir -p ~/.ssh
curl -s "https://api.github.com/users/$GITHUB_ACTOR/keys" | jq -r '.[].key' > ~/.ssh/authorized_keys
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

安装 cloudflared

之后我们安装 cloudflared 并连接到 Tunnel: 这个动作需要 connect token, 在后边创建 Tunnel 的时候会获取到, 这里我们先写好 “占位符”, 并在之后添加到 Repo Secret, 进而传递到 Workflow, 并通过环境变量在 Shell 中使用:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Connect to Cloudflare Tunnel
        env:
          CLOUDFLARE_TUNNEL_TOKEN: ${{ secrets.CLOUDFLARE_TUNNEL_TOKEN }}
        run: |
          curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
          sudo dpkg -i cloudflared.deb
          sudo cloudflared service install $CLOUDFLARE_TUNNEL_TOKEN

阻塞构建进程

最后, 我们使用 alexellis/block-with-tmux-action 这一 Action, 放置在需要 “暂停” 的地方; 这个 Action 将会安装 tmux 并阻塞构建过程.

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Setup a blocking tmux session
        uses: alexellis/block-with-tmux-action@master

综上, 整个 Workflow 文件类似如下:

name: Debug Build
on:
  workflow_dispatch:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup SSH server for Actor
        run: |
          sudo apt update && sudo apt install -qy openssh-server
          echo "PasswordAuthentication no" | sudo tee -a /etc/ssh/sshd_config
          echo "ChallengeResponseAuthentication no" | sudo tee -a /etc/ssh/sshd_config
          echo 'Match Address 127.0.0.1'        | sudo tee -a /etc/ssh/sshd_config
          echo '    PasswordAuthentication yes' | sudo tee -a /etc/ssh/sshd_config
          echo '    PermitRootLogin yes'        | sudo tee -a /etc/ssh/sshd_config
          sudo systemctl daemon-reload
          sudo systemctl restart sshd --now
          mkdir -p ~/.ssh
          curl -s "https://api.github.com/users/$GITHUB_ACTOR/keys" | jq -r '.[].key' > ~/.ssh/authorized_keys
          chmod 700 ~/.ssh
          chmod 600 ~/.ssh/authorized_keys
      - name: Connect to Cloudflare Tunnel
        env:
          CLOUDFLARE_TUNNEL_TOKEN: ${{ secrets.CLOUDFLARE_TUNNEL_TOKEN }}
        run: |
          curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
          sudo dpkg -i cloudflared.deb
          sudo cloudflared service install $CLOUDFLARE_TUNNEL_TOKEN
      - name: Setup a blocking tmux session
        uses: alexellis/block-with-tmux-action@master

创建 Cloudflare Tunnel

可以在 Cloudflare 的在线面板上进入 Zero Trust 业务, 创建一个 Tunnel.

这里我们先记下 connector token, 并添加到仓库的 Secret 中, 名字需要和 Workflow 中一致, 本文中为 CLOUDFLARE_TUNNEL_TOKEN.

之后添加一个 “public hostname”, 需要为一个独立的 domain, 而不是某个子目录; 对应的服务填写 ssh://127.0.0.1:22.

为了控制权限并且能从 Web 访问到这个 SSH 服务, 我们在新建一个 Application, domain 为上一步中的 “public hostname”. 需要记得设置访问策略, 并打开对 SSH 的网页渲染功能.

连接到 Runner

完成后便可以触发这个 Workflow 了, 观察日志, 等待执行到阻塞处, 在浏览器中访问前面设置的 “public hostname” 即可. 登录后按照提示输入 GitHub 上 SSH 公钥对应的私钥, 即可连入 SSH.

连入后, 执行 tmux attach, 就可以进入当前 Runner 执行到的位置. 在完成调试后, 输入 exit 退出, 工作流便会继续执行.

---

参考文档:

Connect with SSH through Cloudflare Tunnel - Cloudflare Zero Trust Docs