Skip to main content


An image is a compressed package that contains the settings and the file system to spawn a runner (container) in order to run a job. The user declares the image to use for a job in the .bbx/config.yaml file. This document describes how to use images to create runners to run pipelines.

BeetleboxCI includes a registry to store images locally and BeetleboxCI has the capability to use both local and remote images when running pipelines.


A runner is a container used to run a job. Each runner is designed to run specific design environments, ensuring that they have resources and relevant tools. BeetleboxCI can use images from the local registry or from any external registry in order to orchestrate containers.

The figure below shows an example of what the contents of the local registry may look like:


Setting up runners in workflows

To use images to set up runners in workflows, you must provide the runner name as an image within your config.yaml file. In the following example, the ubuntu-generic is first located in the image registry and the used in the config file through the image key.

image: ubuntu

Once you have defined a runner, you can define a workflow with jobs that use the runner you defined earlier. When you run this workflow, BeetleboxCI will orchestrate a container using the ubuntu image defined above.

image: ubuntu
runner: example-runner
current_working_directory: ~/
- run:
name: Say Hello World
command: echo "Hello World"

- hello-world


BeetleboxCI cannot use images which have underscores in their names. Attempting to use such images will result in the job failing with an error.