Skip to content

Karrot release process

This doc explains how the build and release system works in Karrot.

🚧 Recently changed

This process has recently changed, so all a bit new!

Forgive us if some edges are rough.


When you push to main branch or a tag of karrot-frontend or
karrot-backend it triggers the CI to run a build process.

You can see the build job status over at karrot-frontend builds and karrot-backend builds .

These each build and publish a docker image.

karrot-frontend images:

docker pull

... and karrot-backend images:

docker pull

Docker tags

The latest image tag refers to the main branch in git.

For tagged builds, the git tag and the docker tag is the same, e.g.:

docker pull
frontend .tar.gz archive

Additionally, the frontend is published as a tar.gz archive of the build files, ready for serving, see karrot-frontend archive.

This does not come with an appropriate nginx config, so you're on your own for that. You can borrow ideas from docker/nginx.conf.template.


Releases are found over at karrot/releases.

This brings together the frontend and backend images, the changelog, plus any release notes.

For each release, it gets a version number, e.g. v14.0.0.

We release both the frontend and backend with the same version number, and you must always run matching frontend/backends.

How to release a version

🚧 Work in progress

This might get refined into a single process in the future once the process settles down

Merge all changes

Make sure all changes you want to release are in the main branches of each repo.

Wait for tests and builds

Wait to see the main-branch tests and builds complete, and only proceed if they are successful.

Wait for deployment to

The latest version that has just been built will be automatically deployed to

Check that deployment was successful, then go and visit it and check if your intended changes are working nicely!


All changelong entries go in the frontend changelog file, so we need to update the first.

Update karrot-frontend/

  1. add your new release version in the [Unreleased] section with a date
  2. add entries for all changes made since previous release if it's not already been done
  3. prepare the release

Now we can push the frontend tag:

git push
git push origin vYOUR.VERSION.NUMBER

Why two pushes?

The release script makes a commit to the main branch, then tags that, so we want to make sure remote main branch is up to date.

You could also use:

git push --tags

Which does both (I think!), but maybe also pushes other tags.


This is easier, just tag and push:

git push origin vYOUR.VERSION.NUMBER

Check builds again

Go and look at build status and see if they worked.

Optionally try them out

If you have a way to run Karrot with specific images, you could try out those built images yourself before proceed.


I have a docker-compose.yml-based karrot setup on my local machine (using karrot/karrot/src/branch/main/docker-compose) where I can pop in an image reference and try it out to make sure it basically works.

Tag karrot/karrot

karrot/karrot is a repo that ties together the frontend and backend for the purposes of releases.

Make sure you have that checked out with the submodules:

git clone --recurse-submodules


I have a clean checkout of this that is separate to my frontend/backend repos that I use when I'm coding. Up to you though.

Now we can create the release tag:

./scripts/release-tag v14.0.1

This will:

  • pin the submodules to the right commit for that tag
  • create the tag in karrot/karrot
  • print a nice message telling you can push it
git push --tags

Create the release

Go and visit and press the "New Release" button.

Put in the tag you chose before, the name can also be the tag name.

For the description you want:

  1. a brief human description of the changes
  2. the info about how to get the docker images + tar.gz release (copy from a previous release and update tags)
  3. the changelog, you can just copy it from karrot-frontend changelog


There is a good case for creating some automation for this, esp. creating the docker image info.

You can mark it as pre-release if you are not sure it's ready for consumption yet, then come back and uncheck that later.

Co-op Cloud recipe

Also, consider updating the Co-op Cloud Karrot recipe over at

Deploy to on yuca

If you want to deploy it to, your current option is by using ansible on your own machine.

See Using ansible directly.