cimpler is a very simple Node.js continous integration server that interfaces with Github post-recieve hooks and the Github commit status api.
It's super simple to setup and configure. At this time it's designed to only manage one repo at a time.
The most common usage won't be direct at all. i.e. Github post-recieve hook triggers build, build status and log are reported to Github commit status api, you view build log in the browser.
cimpler provides an easy CLI:
$> cimpler --help
Examples:
cimpler build [-b branch-name] trigger a build on the current repo
cimpler status echo the list of builds in the queue (* means building)
Options:
--command, -c Custom shell command to execute for this build (instead of
the one from config.js)
--branch, -b Name of the branch to build (defaults to current)
--verbose, -v Produce more output for the status command. Includes details for each build.
--port, -p HTTP port of the cimpler server (defaults to value in config.js)
Note: The most common usage won't need the cli at all. i.e. Github post-recieve hook triggers build, build status and log are reported to Github commit status api, you view build log in the browser.
But, cimpler does provide a nice CLI
$ git clone https://github.com/danielbeardsley/cimpler.git
$ cd cimpler
$ npm install --production
$ cp config.sample.js config.js
Add your server's url (and port) as a github POST receive hook (http://www.example.com:12345/)
$ vim config.js # Edit to your liking, config.sample.js is well documented
If you are using the github plugin,
make sure the config.httpPort
is accessible from the outside
(or at least from github's servers).
$ node server.js
$ npm install
$ npm test
The architecture is very simple and based on plugins. A plugin has access to several methods and events. Please look at the existing plugins as a guide to writing your own.
A plugin is a node.js module that exports an object which has an init
property like: function(config, cimpler)
-
config: The value from the corresponding entry in config.js ("some value" from below)
// config.js module.exports = { plugins: { 'plugin-name': "some value" // passed to the init() function }, ... }
- If
config
is an array, theinit()
function will be called once for each value in the array. This allows you to configure multiple instances of a plugin.
- If
-
cimpler: an instance of Cimpler which exposes methods and events
- Methods:
.addBuild(build)
: Adds a build to the system. A build is an object with these properties at a minimum:repo
: a string identifying the repository of the build (a url, a local path to the originating repo)branch
: The name of the branch this build should be run against
.consumeBuild(callback[, repoRegex])
: registers this plugin as a build consumer.callback
has signature:function(build, started, finished)
started()
andfinished()
are both functions a plugin should call when a build is started and finished.started()
and thebuildStarted
event will be triggered implicitly iffinished()
is called first.
- If
repoRegex
is provided, only builds with abuild.repo
property that match the regex will be passed to the callback. - The callback will be called for each build, serially.
callback()
will only be called for the next build oncefinished()
is called.
.shutdown()
: Initiates shutdown of the server and triggers theshutdown
event.
- Events:
buildAdded(build)
: Emitted immediately aftercimpler.addBuild
is calledbuildStarted(build)
: Emitted after a build has been started by a build consumerbuildFinished(build)
: Emitted after a build has finishedshutdown
: Your plugin should release it's resources because the server is shutting down.
- Methods:
- Node.js (0.6 and above)