Skip to main content

BeetleboxCI YAML Tutorial

This document introduces the concepts in BeetleboxCI config.yaml files.

Getting started​

This guide introduces the following topics:

  • How BeetleboxCI interacts with config.yaml
  • Triggering a workflow
  • Using runners to specify the environment where a job runs
  • Issuing shell commands

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.

Create a Config File​

  1. To begin, you can create an empty repository in Github (or other VCS if you prefer). We recommend creating this repository with public access for simplicity.
  2. Create a .bbx folder inside the repo
  3. Create a config.yaml inside the .bbx folder.

Specify a Runner​

Paste the following code into the config.yaml file. 

runners:
 local-runner:
  image: public.ecr.aws/y2s4f3y9/ubuntu-generic:latest

The code declares a runner called local-runner that will be used to run a job. It is possible to declare multiple runners in the case where you wish to use different runners for different jobs in a single config file. The image field specifies a docker image that will be used to create the runner. Beetlebox provides an Ubuntu image called ubuntu-generic and this is available through an image registry that we have made public. You may wish to use any other publicly available Linux-based image from Dockerhub as an alternative.

Issuing Commands​

Paste the following code into the config.yaml file, below the code you pasted above. 


jobs:   
 hello-world:
  runner: local-runner
  steps:
   - run:
      name: Say Hello World
      command: |
       echo "Hello World"

This code declares a job called hello-world which will will be executed on the runner we declared earlier. It is possible to declare multiple jobs under the jobs label. A job contains a series of steps (in this job, only one step). The steps label lists a series of run directives. Each run directive is executed in the sequence that they are defined. Each run directive has a name and a command. The name field is used to identify each step. We recommend that the name field is given a unique, meaningful value. The command field lists a series of shell commands to be executed on the runner during each step. In this case, we print Hello World.

Declare a Workflow​

Paste the following code into the config.yaml file, below the code you pasted above. 

workflows:
 hello-world-workflow:
  jobs:
   - hello-world

This code creates a workflow called hello-world-workflow. It is possible to declare multiple workflows under the workflows label. A workflow contains a series of jobs (in this case, only one job). The hello-world-workflow instantiates and lists the job called hello-world, which we declared earlier. It is possible to list a series of jobs here that have been previously declared.

Next steps​

Your config file should now look like this:

runners:
 local-runner:
  image: public.ecr.aws/y2s4f3y9/ubuntu-generic:latest
jobs:   
 hello-world:
  runner: local-runner
  steps:
   - run:
      name: Say Hello World
      command: |
       echo "Hello World" 
workflows:
 hello-world-workflow:
  jobs:
   - hello-world
  1. Commit and push the config.yaml file to your repo.
  2. You will now be able to add your Git repo to BeetleboxCI to run it.

Create a pipeline​

You can now head over to your BeetleboxCI application in your browser to begin these steps.

  1. On the pipelines page of BeetleboxCI in your browser: If you do not already have any pipelines in BeetleboxCI, click 'Create your first pipeline'. Otherwise, click "Create Pipeline" at the bottom of the pipelines page.
  2. In the following screen, fill in the following (assuming you are using a public repository on Github):
  1. Click proceed. You will now be redirected to the pipelines page where you can see the project that you just created.
  2. On the pipelines page, click hello-world so see the workflows in this pipeline
  3. Click the run button on the top right hand corner of the workflows list. The pipeline will begin running and it should take around 30 seconds to complete.
  4. You will see "Passed" on the hello-world pipeline once it has completed.