Skip to main content

Introduction to Beetlebox CI Concepts

This document will give a brief summary of the concepts used by BeetleboxCI.


BeetleboxCI is aimed to make continuous integration seamless and simple for engineering designs in the FPGA, ASIC and IOT space. CI flows have many associated concepts that are designed to be re-usable. The following image shows the basic concepts of BeetleboxCI:



A pipeline is the complete collection of automated processes that are to be run when a run is triggered. Each project will have a single pipeline but the pipeline may have many branches. When a project is triggered to run, it will pull code from the git repository and configure a pipeline through the configuration file.


When code is committed to Github, a message is sent to BeetleboxCI that a code change has occured. This message acts as a trigger for BeetleboxCI to begin the automated processes in the pipeline.

Configuration files

BeetleboxCI follows configuation-as-code principles. This means that the entire pipeline in the project may be described in a configuration file that is placed at the root of your git repository in .bbx/config.yaml. This allows the configuration to be versioned and changed just as an other part of the git repository.

+-- Project files
+-- .bbx
| +-- config.yaml

Full details of the configuration file YAML can be found in the BeetleboxCI YAML configuration document.


Workflows are used to organise jobs into a distinct run order. A pipeline consists of multiple workflows that define the entire build and test process. Individual workflows are defined in the config.yaml file.

For more information on workflows, please see the following document


Jobs are a distinct set of steps that are to be run as part of the pipeline. They are also used to define the runner that will be used to execute these tasks. Each job is defined in the config.yaml file.

For more information on jobs, please see the following document.


A runner is a container used to run a job. Every job is provided a clean execution environment that are used to run the job's steps. BeetleboxCI runners are designed to provide the tools and software needed to run jobs.

For more information on runners and the runner store, please see the following document.


A step is a single task to be performed. Typically, these tend to be a series of executable commands running in a shell, such as bash.

For more information on runners and the runner store, please see the following document.


Artifacts are files that have been generated by a job and is kept after the workflow has completed. These files are used for long-term storage and help provide a single file source for all your team. Artifacts may also be uploaded for use in jobs. For example, board files may be uploaded to build for that particular builds.

For more information on artifacts and the artifact store, please see the following document.