CL Continuous Integration

The purpose of this project is to encourage widespread use of continuous integration for Common Lisp projects. To that end, we will gather links to solutions for various CI platforms, as well as implement new solutions.

CI Platforms

In this section, we give an overview of CI platforms and solutions built on those platforms, tailored for Common Lisp projects.

We know this section is likely woefully incomplete. If you know of others, please open a Merge Request at https://gitlab.common-lisp.net/clci/clci.common-lisp.dev/

Gitlab CI

Gitlab CI is the default CI solution for projects hosted on Gitlab. It uses YAML files to describe jobs and pipelines. Documentation can be found at https://docs.gitlab.com/ee/ci/.

Gitlab CI is very flexible and seems to have grown organically over the years, with new features being continuously tacked on instead of starting out with a concrete, modular design. This has both pros and cons.

As a pro, it's very simple to get started. For example, it is very easy to write jobs: a job is basically a list of strings that will end up being evaluated in a shell.

As a con, it has some seemingly arbitrary restrictions. For example, naming a job pages has a special meaning, certain job names are unusable because there are other properties expressed at the same level as jobs (for example include or stages), and some features don't play nicely with each other.

That being said, Gitlab CI is still an excellent choice and should likely be your preferred option if your project is hosted in a Gitlab instance.

Helpers

CLCI Gitlab CI

As part of the CLCI project we have developed a set of helpers for Gitlab CI. To the best of our knowledge, it's the only such project aimed at Common Lisp projects. To date, Gitlab hosted CL projects either don't do CI or have a homebrew set of Gitlab CI scripts.

See CLCI Gitlab CI for documentation of this project.

GitHub Actions

GitHub Actions is a relative newcomer on the scene. It is tightly integrated into GitHub. You should probably consider using it if your project is hosted on GitHub. Its documentation is located at https://docs.github.com/en/actions.

While GitHub Actions has a large allocation of free minutes, you should consider the possibility that may change in the future. Like many CI platforms, GitHub Actions allows you to provide your own runner, thereby getting around the free minutes cap. However, GitHub has questionably decided to allow forks of repositories to run jobs on the upstream's self-hosted runners by default. This presents some serious security concerns if you use self-hosted runners for public projects and GitHub explicitly recommends against it: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners#self-hosted-runner-security

Because it is a relative newcomer, GitHub Actions has the benefit of learning from the mistakes of others. It is very clearly designed from the ground up to be a very modular system with few assumptions.

The downside to this is that it can feel very "enterprise"y and can be very difficult to get started. Everything is very explicit. For example: you must include an explicit step to check out your repository in a workflow.

An upside is that they have made it very easy to share workflow actions. That is, so long as you don't mind writing those actions in JavaScript or piecing them together from other actions.

Helpers

40Ants

As part of the 40 Ants organization, svetlyak40wt has developed 40ants/ci. This project allows you to write some CL code describing GitHub Actions Workflows and then they are translated into the YAML files needed for GitHub Actions. By its own admission, it is very opinionated, and that may be a turn off for some folks. However, it appears to be of high quality and is worth checking out.

In addition to the workflow generator, the 40 Ants-verse has developed several individual Actions that can be used in any workflow. See:

3B

3b has put together several blog posts on using CL with GitHub Actions.

Unfortunately, it's not something you can just drop into your repo and have it work, but he does show how you can build your own workflows using several tools that are not the 40Ants tools.

Travis CI

Most CI Platforms these days owe their success to Travis CI. Travis was one of the first (if not the first) commercial CI platform that opened its doors to projects for free and started to get devs to really use CI. Travis CI documentation can be found at https://docs.travis-ci.com/.

Unfortunately, Travis has fallen far from its perch after an acquisition by Idera. They still offer free credits to Open Source projects. But in reality, these credits are very difficult to obtain. New projects should likely not use Travis CI unless they are willing to pay. Existing projects that use Travis CI should consider moving to another solution or pay.

Since Travis CI is one of the oldest CI platforms out there, it additionally comes with a lot of baggage. While modern platforms make it trivial to have CI pipelines that do more than just run tests, it is not so obvious how to do that on Travis. The easiest thing to do with Travis is write a script that depends on environment variables, and then Travis will run it N times for you, with the values of the variables chose from a matrix.

Helpers

CL Travis

The CL Travis Project is probably the best resource for using Travis CI with CL projects.

The biggest concern with CL Travis is likely that it use CIM (a deprecated project) under the hood. Additionally, it has hard coded versions of CL implementations that it uses. These versions do seem to be kept up to date, however.

Roswell

Roswell's wiki has some information on using Roswell on Travis CI. See https://github.com/roswell/roswell/wiki/Travis-CI.

Roswell must build several implementations locally in order to use them. So if you use Roswell, be sure to look at their section on caching to ensure that you don't continuously waste time building the same implementation over and over again.