GitLab runner on balena devices for continuous integration testing



Here’s a project I wanted to share with you. I’m very much interested in automation, and recently was playing with the continuous integration/continuous delivery (CI/.CD) tools that GitLab provides. Their platform allows you to add your own “runners”, devices that are running the testing/building/deployment jobs. Inspired by that, I wanted to create an easy way to add balena devices as runners to GitLab (either the platform or your own open source GitLab installation).

The result is the following project:

What it does:

  • the gitlab-runner for a given platform
  • you only have to supply the GitLab runner token to register it, otherwise it is set up with good default values, that you can also change
  • it registers your runner to GitLab, adds device type, architecture labels to your runner (so e.g. you can say "I want this job to be run on a raspberrypi3", or “… on an armv7l device”)
  • the runner is using the onboard docker/balenaEngine, and has an added garbage collector, so that the docker images are not going to fill up your device, hopefully
  • after the first automatic registration you can use gitlab-runner in the container to register the device to more than one projects (or use the GitLab dashboard to assign a runner to multiple projects)

To try it out, you can do the following:

Create a new balena application, and push the above project to it. Then take a device you have, and provision into that application.
If you don’t yet have a GitLab project to test, you can use this following one, just clone it on GitLab:

It has set up a small piece of code (a shell scipt that gets you a piece of advice, in nice colours!), and some testing instructions in .gitlab-ci.yml.
Once you cloned it, go to your projects Settings > CI/CD page, and select Runners. To make sure that you are using this new runner, click Disable Shared Runners on that page. Take note of the runner registration token:

Find the device you provisioned, and add a new service variable for the runner service called GITLAB_TOKEN with the value of your token.

If things go well, your device will automatically register and will show up in a short time, after you refresh the page, something like this:


Afterwards, you can go to to the project’s CI/CD > Pipelines page, where you would see something like this.

(It might happen, that the shared runners already run the job first when you cloned the project before they were disabled, you can clock on a result, and on the next page you can re-run it with the new runner you have).

In the balena dashboard, you might see something like this in the device’s logs, which shows it’s running something:

And this is how the test logs are shown in GitLab:

Congratulations, you should be ready to run build jobs on your own devices!

One of my jobs, run on a Raspberry Pi 3 can be found here:

The way it is set up, the same runner repository linked above works across architectures, I’ve tried on Raspberry Pi 1 (armv6), Pi 3, BeagleBone (armv7), ARTIK710 (aarch64), NUC (x86_64), Edison (i686).

To showcase the multiarchitecture nature of things, I’ve set up a variant of the above demo project, with this little testing rig:

These are 5 physical devices + a Virtual NUC on my laptop, a 5 different architecture, and they are building the test cases according to their device type tags.

You can see the results in this test run:

(feel free to click around, and check the test results, that they were run on the actual device types, shown by the output of /proc/cpuinfo saved with the tests)

Extra Notes

The code sets up the runners by default to use the balenalib/%%BALENA_MACHINE_NAME-debian:latest image (ie. if your .gitlab-ci.yml does not speciy an image, that’s going to be run).

You can see more notes, and the environment/service variables that can modify the behaviour of the automatically registered runner in the readme:

If you want to know more about GitLab runners, check out their documentation and possibly their advanced configuration notes, which might come handy, if you want to register extra runners. That you can do by connecting to the runner service in the web terminal or over balena ssh, and check out gitlab-runner --help.

For further details on the GitLab CI/CD infrastructure, check out their docs.

If you want to check out the runners’ source code, here’s the repository for that too:

What’s next?

There are definitely a lot of things to improve on (configuration, ease of use, etc…). If you find any problem or have an idea for improvement, please open an issue! Or if feeling adventurous, send a Pull Request with your changes! :slight_smile:

Or just ask here of you have any questions, share with us if you have some success story testing code with this project! Cheers!


very nice project! Congrats


Thanks, @gusgonnet, if you happen to use this project for something, would love to hear about it! :slight_smile: