Builds are the central component of MonkeyCI. They are the whole reason you're using this tool! Every time a change is detected in one of the configured repositories, a build is triggered. If you have set up a build script in the .monkeyci/ directory, it will be executed as a single build.

Sometimes you just need to run something on your local machine. This is of course not advised for production purposes, but every once in a while, it can be useful to run the full build pipeline on your own machine. MonkeyCI makes this possible, as long as you either have Docker or Podman on your machine.

A build script consists of one or more jobs. There are two kinds of jobs: action jobs and container jobs. A job can be dependent on other jobs, which is indicated in the job configuration. In addition, jobs can require or produce artifacts, or they can use caches.

In order for a build to run, it must first be triggered. MonkeyCI has several ways to do this:

Build parameters are a way to configure your builds, without having to put this configuration in your build script itself. It is typically used for sensitive information like credentials or signing keys.

Learn how to use artifacts in order to share information between jobs, and make them available for download.

Where artifacts can be used to pass files between jobs, caching is meant to pass files between the same job, over different builds. Jobs that specify a caching entry with the same id will restore the files pointed to in their configuration before they start, and store it back after they have finished.

As with all coding, or actually, with everything, you want to test things before you roll them out. Similar to your production code, which of course you write using TDD, you'd want to be able to write tests for your build script. After all, it may be important. When you're writing things thay may deploy directly into production, it seems self-evident to test this thoroughly before running it against a live environment.

In many situations your builds will differ depending on the situation. For example, you'll only want to deploy building a release, or when building from the main branch, or when files in a specific directory have been touched. And your deployment strategies may differ depending on the environment where you'll be deploying (staging vs. production). For this, you'll need conditions.

For any publicly accessible application, security is important. MonkeyCI is no different. We generally advise against using any kind of sensitive or private information in your builds. Similarly, it's a bad idea to commit that information in your repositories, especially if they're public. But we also realize that in order to do decent integration tests or deployments, it's often unavoidable to put credentials or ssh keys in build parameters. MonkeyCI ensures that this information is only visible to the appropriate users. To this end, the build parameter values and ssh keys are encrypted at rest. This means they are stored in an encrypted manner in the database. It's only when editing them or when using them in a build that they are decrypted.

A push consists of one or more commits, and each commit is about one or more changed files. In MonkeyCI it's possible to retrieve which files have changed in the commit if the Git platform passes this information in the webhook request.

Labels are used extensively throughout MonkeyCI to group several kinds of objects for various purposes. The main applications for labels are:

If you are working on open source projects, the git repositories that contain the code will usually be public. But sometimes you also wish to enable builds on private repositories. These can only be accessed if an SSH key is provided when pulling the code.

Some of you may be wondering if there is some overlap with Babashka, the excellent Clojure implementation for your shell. MonkeyCI is in no way intended to replace (or be replaced) by Babashka. On the contrary, both tools complement each other.

This is a listing of the available functions when writing build scripts. Since MonkeyCI is open source, you can also check out the code and see for yourself. The API code is located in the monkey.ci.api namespace. They cover a range from low-level to high-level functions. It is advised to use the high-level functions in monkey.ci.api, unless you want to do something very specific, in which case you may also find useful functions in monkey.ci.build.core or any other adjoining namespace.