Contigrator documentation

What it is, and what it does!

contigrator is a tool for continious integration.
It can be used to automatically build software when certain events happen,
for example when a change is submitted to a gerrit server, or when new
commits are pushed to GitHub. It can also monitor a git-repository and
automatically build when it finds new changes.

In practice anything can be build with contigrator, software-projects,
large and small (Wizznic and Android), anything which is kept in git and
benefits from having an automated process for putting it together into its
final form.

Definitions

To avoid misunderstanding, here is a list of words and their meaning
in contigrator context.

 * workspace - The workspace is where the files which are to be build is
   placed.

 * job - Executing jobs is the basic task of contigrator.
   A job is configuration files, scripts and a workspace, jobs execute
   scripts inside the workspace and handles the result according to
   the configuration. It is those scripts which does the building.
   The word project is not used, since nothing prevents a job from
   being configured such that it will build several software projects
   in order to produce one final software-package (Android for example).

 * output - The file or files which are generated during building, and
   should be kept after the workspace is cleaned. The output are what you
   give to testerso or users. Jobs are not required to have output.

 * build - A build is the result of the build.sh script being run by a job.


Features

contigrator is minimalistic, so much that its name starts in lowercase.
But it is not completely useless, here are the main features:

 Starting (triggering) builds:
 * Builds can be started by a ServiceHook on GitHub.
 * Projects on gerrit can be monitored for changes and builds started.
 * Git repositories can be monitored for changes and builds started.
 
 Configuration:
 * Set which builds should be kept forever (made permanent)
 * Set build online availability based on exit status
 * Set build-history length
 * Set number of (non-permanent) builds should be kept
 * Set if logs should be available online
 * Per-job user script that is run on build-success
 * Per-job user script that is run on build-failure
 * Per-job user script for building the job.
# How to do a minimalist manual: Add 4 main sections. 1.0 Installation 2.0 Config 3.0 Creating and configuring jobs 4.0 Starting builds # 1.0 Installation (Create, Extract, Grant, Link, Run ) Requirements: * Webserver with PHP * Bash * Sudo * bc * contigrator expects its root directory to be named contigrator. Step 1. Create a user for contigratork (call him contigrator), become contigrator. Step 2. Extract contigrator to /home/contigrator/contigrator (or for example /var/lib/contigrator ) Step 3. Grant sudo access for www-data to execute hookTrig.sh as contigrator, add to sudoers: www-data ALL=(contigrator) NOPASSWD: /home/contigrator/contigrator/tool/hookTrig.sh Step 4. Link /home/contigrator/contigrator/web to /var/www/contigrator or something like that. Step 5. Run contigratord. - This is the sleepy program which will lurk in the darkness, just waiting to wreak havoc on your jobs. You could run a screen with the contigrator user, cd to /home/contigrator/contigrator and execute: ./tool/contigratord.sh then detach the screen. You could also: cd /home/contigrator/contigrator/ && ./tool/startcontigratord.sh (and simply use killall contigratord.php to kill it). # 2.0 Config If you want to install contigrator to another location than /home/contigrator/contigrator/ you need to edit cwd in web/hook/github-webhook.php You can set the next build-number in the projects meta-directory. # 3.0 Creating and configuring jobs Step 1. Create a new job: As contigrator user, cd to /home/contigrator/contigrator/ and execute ./tool/newJob.sh answer questions, press enter. Step 2. Edit /home/contigrator/contigrator/jobs/JOBNAME/script/build.sh Optional Step 2.1. If you want to keep track of changes to your build-script, you could add the contigrator buildscript somewhere in your project directory and have /home/contigrator/contigrator/jobs/JOBNAME/script/build.sh be a symlink to that file. Note that this exposes your server to the risk of someone compromising your source-code repository or contigrator, and gaining shell-access with the contigrator user account, therefore it should not be done, ever.. Step 3. Just kidding, you're done, have a look at the meta directory in /home/contigrator/contigrator/jobs/JOBNAME/ it has logs 'n' stuff. # 4.0 Starting builds. contigratord will start building a job when that job is "triggered", jobs can be triggered in the following ways: * GitHub WebHook (In your GitHub projects settings, go to Service Hooks and select WebHook, have it point to http://yourserver/contigrator/hook/github-webhook.php - When you use this, you need to give www-data that sudo access mentioned in installation step 3. * Cron (for periodic builds, it does an update and if nothing new was found, nothing is build ) - Simply follow instructions on job-creation, do crontab -e and add the line as you're instructed. * Manually (For testing your build configuration). - execute ./tool/trigBuild.sh jobs/JOBNAME/ * Writing your own hook, your hook must change directory to /home/contigrator/contigrator/ and then execute ./tool/trigBuild.sh jobs/JOBNAME/ 'REASON' - The REASON is included in the TrigLog.htm file and can explain what caused the hook to trigger the build (For example what changed). You're done, enjoy. Jimmy