Skip to main content

BeetleboxCI YAML configuration

This is the reference for the configuration of config.yaml files. Configuration files are held in the directory .bbx/config.yaml of the Git Repository. If you do not know 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.

KeyRequiredTypeDescription
<runner_id>YMapThe 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.

KeyRequiredTypeDescription
imageYMapThe 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: ubuntu-vitis-2020-1

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 is present. There is no limit on the number of jobs that may run in parallel.

KeyRequiredTypeDescription
<jobs_id>YMapThe 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.

KeyRequiredTypeDescription
runnerYStringThe name of the runner to be used for this job.
typeNMapThe type of the job. This is used to determine what the job is being used for.
current_working_directoryNStringThe current working directory of the machine once booted. If it is not set, the default value of ~/ will be used.
dependsNMapIdentifies the name of the jobs that must successfully complete before this job is run.
inputNMapArtifacts that are to be inputted from the artifact store for use by the job.
outputNMapThe files that are to be saved from the job environment and stored as artifacts in the artifact store.
stepsYListSteps are the tasks that a job is to perform.

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>.type#

A job type is used to indicate the purpose of a job. The job may either be a build or a test type. Build type jobs are used to build or synthesis a design. Examples of build type tests include building software for Vitis or synthesizing block diagrams in Vivado. Test type job types are used to run tests. Examples of such tests may include using logic simulators.

KeyRequiredTypeDescription
buildNMapIndicates if a job is used to build or synthesis designs.
testNMapIndicates if a job is used to test designs.

jobs.<jobs_id>.type.build#

A build type job is used to build or synthesize designs. The build job type may further be specified by providing one of the following names:

  • software: Used for building generic software, such as C/C++ builds.
  • sw-emulation: Used for building designs that are to be emulated using QEMU or other software emulators.
  • hw-emulation: Used for building designs that are to be partially simulated through logic simulators and partially simulated through QEMU.
  • hardware: Used for building hardware that is to be run on FPGA hardware, such as hardware. Example
jobs:    first-job:  type:    build: software

jobs.<jobs_id>.type.test#

A test type job is used to run tests. The test type may further be specified by providing one of the following names:

  • sw-emulation: Used for running designs that are to be emulated using QEMU or other software emulators.
  • hw-emulation: Usetd for running designs that are to be partially simulated through logic simulators and partially simulated through QEMU.

Example

jobs:    first-job:  type:    test: sw-emulation

jobs.<jobs_id>.current_working_directory#

Sets the current working directory of the image. Git repositories will be automatically placed in this directory. If not set, the defaul 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 plave 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.
KeyRequiredTypeDescription
artifactYListThe 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 finised execution.

KeyRequiredTypeDescription
artifactYListThe 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.

KeyRequiredTypeDescription
runYMapRun 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.

KeyRequiredTypeDescription
nameYStringThe name of the step.
commandYStringThe specific command to be run.
typeNStringThe 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 command-line programs to be invoked. By default command is executed on a bash shell.

Example

jobs:    hello_world:  steps:   - run:      name: Say Hello      command: echo "Hello World"
jobs.<jobs_id>.steps.run.type#

A step type is used to indicate the purpose of a step. The following type options are available

  • sw-emulation Used to indicate a step is to be used for software emulation.
  • hw-emulation Used for a step that is to be used for hardware emulation.
  • hardware Used to indicate a step is to be used for hardware.
  • miscellaneous The default value. When a step does not fit into any other category.
jobs:    run_software_emulation:  steps:   - run:      name: Say Hello      command: emulation-sw/build.sh      type: sw-emulation

workflows#

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

KeyRequiredTypeDescription
<workflow_id>YMapThe ID of a workflow.

workflows.<workflow_id>#

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

KeyRequiredTypeDescription
jobsYListThe 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