BeetleboxCI YAML Reference

This is the reference for the configuration of config.yaml files. The entire build, simulation and deployment process can be specified by the configuration file (config.yaml). The configuration file is stored in the directory .bbx/config.yaml in the the root folder of your repo. They are written in YAML syntax. If you are not familiar with YAML, please see this guide.

runners

Required. The runners that are used in this pipeline. Runners provide the execution environment for your jobs to run in. Multiple different runners maybe used in the same pipeline so that the optimal choice is used for a particular job.

Key	Required	Type	Description
<runner_id>	Y	Map	The ID of a runner.

runners.<runner_id>

Required. Each runner must have an ID, which is unique. <runner_id> must start with a letter and only contain alphanumerical characters.

Key	Required	Type	Description
image	Y	Map	The runner image used for this runner.

runners.<runner_id>.image

Required. The runner image used for a particular runner. Images provide the OS, the specification, the pre-installed libraries and tools for a runner. Names of runner images, as well as additional information may be found in the runner store.

Example

runners:
 first-runner:
  image: work1-virtualbox:5000/ubuntu-vitis-2020-1:latest

jobs

Required. A workflow is made of one or more jobs. Each job is provided with a runner environment and will by default run in parallel with another job, unless a depends field is present. BeetleboxCI does not enforce any limit on the number of jobs that may run in parallel (unless there is lack of hardware resources on the machine to run a job)

Key	Required	Type	Description
<jobs_id>	Y	Map	The ID of jobs.

jobs.<jobs_id>

Required. Each job must have an associated ID, which is unique. The job ID is used as key and its map is used as configuration data. <jobs_id> must start with a letter and only contain alphanumerical characters.

Key	Required	Type	Description
runner	Y	String	The name of the runner to be used for this job.
privileged	N	Boolean	Specifies whether the container for the job runs with elevated privileges. This allows the container to access hardware on the computer, such as USB ports.
resource_spec	N	String	The amount of resources to allocate to this job.
type	N	Map	The type of the job. This is used to determine what the job is being used for. Currently, it is not necessary to specify the job type, and this label is included for the convenience of the user to label their jobs.
current_working_directory	N	String	The current working directory of the job container. If it is not set, the default value of ~/ will be used.
depends	N	Map	Identifies the name of the jobs that must successfully complete before this job is run.
input	N	Map	Artifacts that are to be retrieved from the artifact store for use by the job.
output	N	Map	The files that are to be saved from the job environment and stored as artifacts in the artifact store.
steps	Y	List	Steps are the tasks that a job is to perform.

jobs.<jobs_id>.resource_spec

The amount of resources to allocate to this job. Defaults to small if unspecified.

Key	CPU	RAM	Type
micro	0.5	2GiB	String
small	1.0	4GiB	String
medium	2.0	8GiB	String
large	4.0	16GiB	String
xlarge	8.0	32GiB	String
2xlarge	16.0	64GiB	String

Example

jobs:   
 first-job:
  resource_spec: micro

jobs.<jobs_id>.runner

Required. The runner that the job is to execute on. The runner provides the OS, specification, pre-installed libraries and tools for the job.

Example

jobs:   
 first-job:
  runner: first-runner

jobs.<jobs_id>.current_working_directory

Sets the current working directory of the image. When running jobs, Git repositories that are cloned will be automatically placed in this directory. If not set, the default value of ~/ will be used.

jobs:   
 first-job:
  current_working_directory: /tools/Xilinx/Vivado/2020.1/

This example will set the current working directory to the Vivado install path and will place the Git repository at this location.

jobs.<jobs_id>.depends

Depends are used to determine what jobs need to successfully complete for this job to start execution.

Example

jobs:   
 first-job:
 second-job:
  depends:
   - first-job
 third-job:
  depends:
   - first-job
   - second-job

In this example, first-job must complete successfully before second-job may start. third-job must wait for both first-job and second-job.

jobs.<jobs_id>.input

input indicate the folder and files that are to be downloaded onto the runner before the job executes.

Key	Required	Type	Description
artifact	Y	List	The artifacts that are to be downloaded onto the runner.

jobs.<jobs_id>.input.artifact

Used to indicate the artifacts that are to be downloaded from the artifact store onto the runner before job execution.

Example

jobs:   
 first-job:
  input: 
   artifact: 
    - example1.zip
    - example2.zip

jobs.<jobs_id>.output

This is used for folders and files that are to be uploaded onto the artifact store once the runner has finished execution.

Key	Required	Type	Description
artifact	Y	List	The artifacts that are to be downloaded onto the runner.

jobs.<jobs_id>.output.artifact

Identifies the artifacts that are to be uploaded onto the artifact store once the runner has finished execution.

Example

jobs:   
 first-job:
  output: 
   artifact: 
    - example1.zip
    - example2.zip

jobs.<jobs_id>.steps

Required. Each executes a series of tasks known as steps, which are able to run commands on the runner. Each step runs in the same environment and has full access to the tools and filesystem of that runner.

Key	Required	Type	Description
run	Y	Map	Run a command.

jobs.<jobs_id>.steps.run

Invoke one or more command-line programs through providing the command string. By default, commands are executed in a bash shell.

Key	Required	Type	Description
name	Y	String	The name of the step.
command	Y	String	The specific command to be run.
type	N	String	The type of the step.

jobs.<jobs_id>.steps.run.name

Required. The name of the step to be displayed.

Example

jobs:   
 hello_world:
  steps:
   - run:
      name: Say Hello

jobs.<jobs_id>.steps.run.command

Required. The commands to be executed. By default command is executed on a bash shell.

Example

jobs:   
 hello_world:
  steps:
   - run:
      name: Say Hello
      command: echo "Hello World"

workflows

Required. A workflow is used to orchestrate and manage jobs.

Key	Required	Type	Description
<workflow_id>	Y	Map	The ID of a workflow.

workflows.<workflow_id>

Required. The unique id of a workflow. <workflow_id> must start with a letter and only contain alphanumeric characters.

Key	Required	Type	Description
jobs	Y	List	The jobs that are to be run in this workflow

workflows.<workflow_id>.jobs

Required. The jobs that are to be run in this workflow.

workflows:
 workflow-example:
  jobs:
   - job-example-1
   - job-example-2

workflows.<workflow_id>.triggers

The jobs that are to be run in this workflow.

Key	Description
manual	The workflow will run when the user presses the run button in the webapp. If no triggers are specified, the workflow can still be run manually using the run button.
push	The workflow will run whenever there is a push to the branch of the repository which the config file is in.
schedule	The workflow will run periodically according to the schedule specified by the cron string. The cron string uses the standard cron syntax.

workflows:
 workflow-example:
  jobs:
   - job-example-1
   - job-example-2
  triggers:
   - manual
   - push
   - schedule:
      cron: "* * * * *"