Assemblage is a continuous integration toolkit. It's intended to provide you with a minimal infrastructure for distributing and performing automated tasks for one or more version control repositories. It makes as few assumptions as possible as to what those things might be.

It's still just a personal project, but if you want to use it I'm happy to answer questions and entertain suggestions, especially in the form of patches/PRs.

Assemblage has three primary parts: the Assembly Server, Assembly Workers, and Repositories.

Assembly Server
Aggregates and distributes events from repositories to workers via one or more Assemblies.
Assembly Workers
Listens for events published by the assembly server, checks out a repository, and runs an assembly script in that repository.
A distributed version control repository. Assemblage currently supports Mercurial and Git.


This example uses three different servers for the three parts, but you can, of course, run all of this on a single host.

You’ll first need a server to manage your assemblies:

example $ sudo gem install assemblage-server
example $ assemblage create-server /usr/local/assemblage
Creating a server run directory in /usr/local/assemblage...
Generating a server key...
Creating the assemblies database...

You can start the assembly server like so:
  assemblage start-server /usr/local/assemblage

Server public key is:

example $ assemblage start-server /usr/local/assemblage
Starting assembly server at:

Now (possibly on a different host) you can create a new worker installation. Workers have a name and a list of tags that describe its capabilities, e.g., the OS it’s running on, installed software, etc. Our example is running on FreeBSD 11, and has Ruby 2.4, Ruby 2.5, Python 2.7, ZeroMQ, and the PostgreSQL client libraries available. We’ll use a pretty simple tag convention but you can make it as simple or complex as you want.

user@example-client $ sudo gem install assemblage
user@example-client $ mkdir -p /usr/local/assemblage
user@example-client $ cd /usr/local/assemblage
user@example-client $ assemblage create-worker \
  -t freebsd,freebsd11,ruby,ruby24,ruby25,python,\
  python27,zeromq,libpq worker1
Creating a new assembly worker run directory in
Set up with worker name: example-client-worker1

Tell it that it should talk to the new server we just set up:

user@example-client $ cd /usr/local/assemblage/worker1
user@example-client $ assemblage add-server \
  --key="&}T0.[{MZSJC]roN-{]x2QCkG+dXki!6j!.1JU1u" \
Talking to tcp://
Registering client `example-client-worker1`...
Requesting a client key...

This will register the client with the server, but it needs to be approved on the server before it can start working:

user@example $ assemblage approve-worker example-client-worker1
Looking for worker registration... found.
Approving connections from example-client-worker1...

Now you can start the worker, which will listen for jobs it can work on.

user@example-client $ cd /usr/local/assemblage/worker1
user@example-client $ assemblage start-worker
Starting assembly worker `worker1`...
Connecting to assembly servers...
   example... done.
Waiting for jobs...

Now we need our repositories to notify the assembly server when events occur. We’ll hook up a Mercurial repo for a Ruby library so that it runs unit tests whenever there’s a new commit. First we’ll install assemblage on the repo server and add the server we’re going to send events to:

user@example-repo $ sudo gem install assemblage
user@example-repo $ cd /usr/local/hg/repos/project1
user@example-repo $ hg init
user@example-repo $ assemblage add-repo \
  --type=hg \
  --key="&}T0.[{MZSJC]roN-{]x2QCkG+dXki!6j!.1JU1u" \ tcp://
Talking to tcp://
Registering repo ``...
Requesting a repo key...

We’ll add a hook to the repository’s .hg/hgrc that looks like:

incoming.assemblage = /usr/local/bin/assemblage send-event commit \
  project1 $HG_NODE

We’ll need to approve the repo registration now too:

user@example $ assemblage approve-repo
Looking for repo registration... found.
Approving repo events from

And finally, we’ll combine all the parts into an assembly called project1-freebsd-tests that will run on a worker with the freebsd, ruby, and libpq tags for each commit to the repo at

user@example $ assemblage add -t freebsd,ruby,libpq \

Now when commits arrive at our repo, it will send events to the assemblage server, which will queue up an assembly. Because the worker we added has all of the required tags, it will:

  • get a notification of the commit
  • clone the repository checked out to that commit
  • look for an assembly script called commit in a directory called .assemblies/ (by default)
  • if it finds one, it will run the script
  • it will then send back any files contained in the .assemblies/ subdirectory with the SHA of the commit (if it exists) along with the exit code of the script.


Primary Public Repos
Git Mirror