Skip to main content

Introduction to Beetlebox CI Concepts

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

Overview#

BeetleboxCI is aimed to make the automation of FPGA designs simple through CI. CI flows have many associated concepts that are designed to be re-usable. The following image shows the basic concepts of BeetleboxCI:

artifact-store-3

Projects#

A project is the top-level concept in Beetlebox CI and is used to automate the building and testing of a code base held in a git repository. A project automates this by pulling code from the repository and putting through the project's pipeline.

For more information on projects, please see the following document

Pipelines#

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

Triggers#

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#

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#

Jobs are 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.

Runners#

A runner is a machine 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 softwares needed to run FPGA jobs. Provided runners can be found in the runner store along with their specifications and tools that are installed on them.

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

Steps#

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#

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.