Install github runner on pynq

To auto test QICK or other software on an actual RFSoC board running a pynq linux kernel, we have installed the github runner software on a ZCU111. This page outlines the steps taken to install and configure your own runner on a RFSoC board or pynq.

Note that the QICK version installed by the action overwrites whatever you previously had installed. But that's fine, assuming that this board is dedicated for use as a runner (which would be wise anyway).

1. Install github runner

To install the github runner, from the home page of the repository, navigate from the Actions tab to Runners (left menu) > New Runner (button) > New Self-hosted Runner (Button). Here you'll find directions for installing the runner which depend on the operating system and architectures. For RFSoC and pynq, choose Linux and Arm64. This will then give instructions which should be executed from an ssh session on the board, an example is below (you should generally use the commands github gives you, which may be more up to date):

Download

mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-arm64-2.311.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-arm64-2.311.0.tar.gz
tar xzf ./actions-runner-linux-arm64-2.311.0.tar.gz

Configuration

cd actions-runner
./config.cmd --url https://github.com/openquantumhardware/qick --token {token}

While this configuration script runs, you can assign a custom tag to this machine which can be used on the github actions script to indicate that certain actions will be run on machines with this tag (which ever is available first). For the ZCU111, we used the tag zcu111.

After the configuration script is complete, you can test that you're actually connecting with github by running the command:

./run.sh

Your runner should also show up under Actions > Runners > Self-Hosted Runners as connected to the repo.

2. Modifying permissions and installations

sudo permissions

Actions running on our pynq-runner don't have admin rights to run commands. To change this, we give password-less sudo to the default user xilinx. We do this by making an alternate sudoer file:

sudo visudo -f /etc/sudoers.d/runner

And in this file, we add the following line:

xilinx ALL=(ALL) NOPASSWD:SETENV: /usr/local/share/pynq-venv/bin/python, /usr/bin/git

Followed by a save and exit.

Installing nbmake

sudo -s
source /etc/profile
pip3 install nbmake

On PYNQ 2.7 it seems necessary to specify an older version, pip3 install nbmake==1.3.0.

Now the github actions should run as prescribed by our test_zcu111.md example (printed at the bottom of this file). However, this requires that we have an ssh terminal window open. Therefore, we setup the runner as a service in the next section.

3. Setting up the runner as a service and daemon

runner service

Stop the runner script (run.sh) if it's running.

Then, in the actions-runner folder, edit bin/actions.runner.service.template and change the ExecStart line to the following:

ExecStart=/bin/bash -c 'source /etc/profile && {{RunnerRoot}}/runsvc.sh'

Now run the following:

sudo ./svc.sh install

This will install a "service" with a name like actions.runner.openquantumhardware-qick.pynq111-2.service (with the repo and runner names, so it will vary). (If you want a simpler name, you could change this in the SVC_NAME variable in the first lines of svc.sh).

This will enable the runner (so it starts automatically after boot). If you want to start it (so it runs now), execute the following:

sudo systemctl start <service name>

And this should complete the installation. The runner service should show up in the list printed by systemctl and you should be able to get a log with systemctl status <service name> or journalctl -u <service name>.

4. Example action for QICK

test

Note that the cleanup step is required because installing the library and running the tests will create files owned by root, which interfere with the checkout.

name: Test ZCU111

on:
  workflow_dispatch:
  pull_request:
  
permissions:
  contents: write

jobs:
  run_test:
    runs-on: [zcu111]
    steps:
    - name: Clean repo
      continue-on-error: true
      run: |
        sudo git clean -ffdx
        sudo git reset --hard HEAD
    - uses: actions/checkout@v4
    - name: Install package
      run: |
        sudo -E -H python -m pip install -e .
    - name: Test notebooks
      run: |
        sudo -E python -m pytest --nbmake --overwrite ./qick_demos/00_Send_receive_pulse.ipynb