CI-tron: The testing gateway

Installation

First, get a CI-tron dedicated gateway. To install CI-tron in the gateway, follow the instructions in https://pmos.ci-tron.dev/.

Warning

Due to a bug in CI-tron, it might be possible that the graphical UI boots to an error related to Cage. You can retry by pressing Ctrl+C, only if your gateway has GPU support. This can always be workarounded by logging through SSH to the root user.

After installation, and until integration of the build image is more ready, you need to modify /config/mars_db.yaml to remove the freedesktop gitlab instance and add the postmarketOS one like below:

gitlab:
  pmos:
    expose_runners: true
    expose_all_runners_by_default: true
    exposed_priorities:
      default:
        acl: null
    url: https://gitlab.postmarketos.org/
    registration_token: <set token>
    runner_type: project_type
    group_id: null
    # 226 is postmarketos/pmaports
    project_id: 226
    access_token: <set token>
    maximum_timeout: 21600

Registration and access tokens need to be generated as follows. For testing, you can create these yourself if you are part of the postmarketOS team. For production usage, reach out to the infrastructure team so they can generate tokens that allow using the runners across the whole gitlab instance.

  • Open pmaports settings: access tokens

  • Click “Add new token”

  • Fill the form out twice as follows, replacing GATEWAYNAME:

    • registration_token:

      • Token name: ci-tron-registration: GATEWAYNAME

      • Expiration date: leave default, it will self-rotate

      • Select a role: Maintainer

      • Select scopes:

        • self_rotate

        • create_runner

    • access_token:

      • Token name: ci-tron-access: GATEWAYNAME

      • Expiration date: leave default, it will self-rotate

      • Select a role: Maintainer

      • Select scopes:

        • self_rotate

        • manage_runner

The CI-tron documentation has more information about the MarsDB configuration.

Adding devices under test to your gateway

Open the CI-tron dashboard. You will see a VPDU section on top. These are virtual QEMU devices, which can be added by clicking the DISCOVER button.

For testing real devices, connect your PDU (phone-harness) to the device running CI-tron. It should then show up as separate PDU in the dashboard, e.g. as pmos_harness-1234567890. If it does not show up, make sure you have a USB cable with data and check the executor logs (journalctl -e -u executor).

If your DUT is already supported (e.g. OP6 and OP6T), then it’s as simple as connecting the DUT to the PDU and clicking DISCOVER. The device should automatically be detected, start training (go through multiple boot cycles to verify that it works), and eventually appear as a runner in gitlab.

If your device is not yet supported, you will need to add support for it to CI-tron. You can find an example in https://gitlab.freedesktop.org/gfx-ci/ci-tron/-/merge_requests/1051. Copy /usr/local/lib/python3.14/site-packages/valve_gfx_ci/executor/server/templates/boots_db.yml.j2 to /config/boots_db.yml.j2 and edit it, while looking at the executor logs as described above.

Alternatively do the changes in your CI-tron checkout and then deploy them with make live-provision TAGS=executor TARGET=$ip.