Box CI Configuration

Box CI configuration defines build pipelines composed of tasks, and which branches and/or tags to run them on.

It goes in a boxci.yaml or boxci.json file in the root directory of your repository, depending on your preferred format.

Box CI configuration is so simple that we can cover everything with an example:

copy code
tasks: test: npm test build: npm run build staging: sh ./ --env staging prod: sh ./ --env prod pipelines: rc-*: ['test', 'build', 'staging'] master: ['test', 'build', 'prod']

This config describes a typical basic CI setup: 2 pipelines to run tests, build and deploy onto either the staging environment if on a branch matching the pattern rc-*, or the production environment if on the master branch.


The defined pipelines are sequences of tasks that run one after another. Each of the above pipelines has 3 separate tasks. Tasks only beging running once the previous task in the pipeline succeeds. If a task fails, no subsequent tasks run.

The names of the pipelines are patterns to match against the build tag or branch. Each build can only match one pipeline - they are tried top to bottom and the first match runs. If no match is found, no build runs. If you want to configure a catch-all default pipeline, define the last pipeline with the * pattern.


The tasks are just shell commands, and are defined in the tasks section of the config. Any shell command that will run on your underlying build machines is valid - what this means in practice is up to you. For instance, if you use the kubectlcommand in your tasks, you must ensure that kubectl is installed on all build machines.

This example covers the two basic strategies of task definition - a raw command for very simple tasks, in the case of test and build, or calling through to scripts for more complex multi-step tasks in the case of staging and prod. These scripts are ommitted from the example, but you can imagine that they go through a multi-step deployment process using scripting language features that aren't easy to inline into a shell command.


It's entirely up to you how you define the granularity of tasks in your pipelines. The point of tasks is better reporting of build runs and especially build failures - you can see at a glance the rough structure of your build and if it failed, roughly where.

With that said, we recommend you keep your tasks fairly broad-scope. Part of the core philosophy of Box CI is that builds should be defined in scripts, in real languages, instead of in an esoteric config DSL for a CI service.

The best rule-of-thumb for this is how easily you can manually run the same build pipelines in your terminal. With Box CI, this can be done by simply copy-pasting a pipeline's task commands, chained together with &&. The point where this command stops being readable is where your tasks are too granular.