MiniCI

The Mini-CI system

minici is a super lightweight CI system written in Ruby.

Simply call it periodically from cron, and it will check out your code from a git repository, update it to the latest version, and run the command that you specify.

In our case, we’re calling Rake, but any command which returns 0 on success, and anything else on error will work great.

Configuration is done using two very simple YAML files:

• minici.yml, which has the general configuration; and
• projects.yml, which defines the projects to be tested

See the *.example.yml files for hints on how these should look.

Emails can be sent on different stages depending on whether the build has failed, just been fixed, or is an ongoing successful build.

Key Aims

• A super light weight CI script with nothing fancy
• Minimal dependencies, simple setup
• Something which runs via cron, not as a daemon
• Must be fast (we want to run it on a Celeron 600MHz)
• It must prevent me from watching the build script run
• If it’s running in cron, it must be threaded so as that a long running build can’t stop all others
• Needs to support rvm out of the box

Dependencies

There is a project Gemfile – install bundler and then run “bundle install” to install dependencies.

• Ruby
• mail gem (2.1.2 works)

Also works with rvm but this is not required to work (just disable it in minici.yml).

Installation

• Create somewhere for it to live (probably under your home)
• git clone http://github.com/aurorasoft/minici.git
• Add an entry in your crontab like :
  */5 * * * * cd ~/minici; minici
• Start setting up your projects (see next section)

Setting up a new project

Setting up a new project to be checked by minici is trivial :

• Create an entry in projects.yml for it, including the URL for the repository, the build command to run.
• minici will notice that the project is missing on it’s next run and check out the project, including moving to the relevant branch.
• Once it’s been made, jump into the project directory (under Projects/ by default) and set up the environment.
  For example, database.yml, and any other settings you may need.

Now, the next time minici is run by cron, if there is a new revision, it will fire up and run the build script you’ve provided.

Depending on your settings, it will email you all the details.

Notification States

There are three main notification states : failure, success and fixed.

failure is triggered whenever a build fails.
success is triggered whenever a build passes and the last build did too.
fixed is triggered when a build passes, but the build before failed.

It’s important to note that only one state is triggered each run – if it’s fixed, we don’t trigger success too.

Notification Actions

Each state can have different actions assigned to it, including code to run (run), what to attach to the email (attach) and who to email (email).

run events are always processed first, so as that their results can be used by attach events.

See rails_project in the projects.example.yml file for an example of using run and attach together.

There are some tokens which can be used within attach and run commands, including :

• $DATE$ which is replaced with the current date in yyyymmdd format
• $REVISION$ which is replaced with the current revision ID

Command Line Options

 --debug              Force debug notices on
 --force              Force building to continue, regardless of lockfiles
 --help               This notice
 --only=project       Only build the project called "project"
 --version            Version information
 --test-email=EMAIL   Test that email delivery works by emailing \"EMAIL\""

Bugs, Shortcomings and Known Issues

• Don’t change the branch after the project has been created, as minici isn’t watching for this kind of change.
  You can change the branch, but you’ll need to go into the project directory and “git checkout” the new branch manually.
• Probably won’t work on Windows, as it tends to use some shell tricks to get everything to work right.
• git reset --hard is run on the working copy before the latest version is pulled, so as to prevent any “not uptodate” issues.
  This means you can’t have local changes to checked in configuration files (which we think is a good thing!)
  If your configuration files need to change on different machines, we suggest they be renamed to be an example file, and your deployment code puts the local modifications it into the correct position.

TODO

• Detect when a Gemfile is present and install it automatically if they have rvm enabled
• Add support for other RCS (eg. Subversion, Hg)
• Comments. Cos, you know, they’re pretty light on at the moment…
• Unit tests. There’s not a lot of code here, but it still needs something!

Ego Trippin’

Minici was built in one evening by Jason Stirk, because CC.rb was incredibly slow and clumsy, and I still can’t get Integrity to fscking well run anywhere.

Minici is in production use at Aurora Software

Licencing

Copyright © 2010 Aurora Software
Released under the MIT license