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.
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...
done.
You can start the assembly server like so:
assemblage start-server /usr/local/assemblage
Server public key is:
&}T0.[{MZSJC]roN-{]x2QCkG+dXki!6j!.1JU1u
example $ assemblage start-server /usr/local/assemblage
Starting assembly server at:
tcp://example.com:7872
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
/usr/local/assemblage/worker1...
Set up with worker name: example-client-worker1
done.
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" \
tcp://example.com:7872
Talking to tcp://example.com:7872...
Registering client `example-client-worker1`...
Requesting a client key...
done.
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...
done.
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" \
http://repo.example.com/project1 tcp://example.com:7872
Talking to tcp://example.com:7872...
Registering repo `http://repo.example.com/project1`...
Requesting a repo key...
done.
We’ll add a hook to the repository’s .hg/hgrc that looks like:
[hooks]
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 http://repo.example.com/project1
Looking for repo registration... found.
Approving repo events from http://repo.example.com/project1...
done.
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
http://repo.example.com/project1:
user@example $ assemblage add -t freebsd,ruby,libpq \
http://repo.example.com/project1
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:
commit in a directory called .assemblies/ (by default).assemblies/ subdirectory with the SHA of the commit (if it exists) along with the exit code of the script.