Configuration

CI-Eye stores its configuration in a series of text files held in the .ci-eye directory located in the home directory of the user who is running the server. When you first start CI-Eye, it creates a default set of configuration files that serve as an example for you to edit. Unless otherwise mentioned, updates to these files will not require the CI-Eye server to be restarted.

Views

CI-Eye is designed around the concept of views, each of which is intended to be radiated independently. If you only have one radiator, you only need to define one view. A single view can contain information aggregated from multiple Continuous Integration servers.

Views are configured in the views.txt file, and are presented in a menu on the welcome page of your CI-Eye server. A sample views file looks like this:

[CI-Eye Demo]
DEMO||Product_Alpha
DEMO||Product_Zappa

[Public Live]
JENKINS|http://ci.jenkins-ci.org|Jenkins core
HUDSON|http://hudson.magnolia-cms.com|Main (trunk, branches, and alternative builds)
TEAMCITY|http://teamcity.jetbrains.com|Gradle
TEAMCITY|http://teamcity.codebetter.com|CI-Eye

This file configures two views, the first being a demonstration view and the second being a more realistic view that aggregates some well-known publicly accessible CI servers.

A view is configured with a name, which identifies it in the menu on the CI-Eye welcome page. In the configuration file, a view name appears in square brackets like this: [My View Name].

Immediately following a view name are one or more lines defining the content for that view. Each of these lines follows a three-part structure, with each part separated with a pipe | character:

1. The type of CI server to talk to (one of HUDSON, JENKINS, or TEAMCITY).
2. The base URL of the CI server to talk to. This should not include a trailing slash.
3. The name of the view/project to radiate build data for. Different CI servers have various names for this concept, but each will have some way to identify a collection of related build targets.

TeamCity from version 8.0 up has the concept of sub-projects to organize your builds. You can address them by using :: (space-colon-colon-space) as the separator between projects and sub-projects, eg

TEAMCITY|serverName|Project Name :: Sub-project Name

Access to Secured CI Servers

By default, CI-Eye assumes unauthenticated (guest) access to the CI servers that it talks to. If your CI server requires a login for access, then you should specify the corresponding username and password as an additional two parameters at the end of the content line. You might want to create a dedicated account for CI-Eye on your server.

For example, if your username was radiator and your password was let-me-in then you might configure a view like this:

[My View]
TEAMCITY|https://ciserver.example.com|My Product|radiator|let-me-in

N.B. If you wish to use the CI-Eye feature allowing builds to be marked as "Under Investigation", and you use TeamCity, then you will need to create an account, as the TeamCity guest account does not allow write access.

Pictures

CI-Eye is very keen that you display pictures for your committers, so that passers-by can see who is checking in. This really gives a sense of what is going on in the codebase, and helps teams to gel.

Pictures are configured in the pictures.txt file, and served from the pictures sub-directory. The sample pictures file looks like this:

[vlad.png]
Vlad the Impaler
vlad
vimpaler
dracula

[stupid.png]
stupid

[gravatar:[email protected]]
john

[doh.png]
-doh-

[all-green.gif]
-all-green-

A picture is configured with a handle, which informs CI-Eye where to obtain an image to display. In the configuration file, a picture handle appears in square brackets like this: [my_picture.png]. Currently, two picture sources are supported: a picture filename (.png .jpg or .gif) corresponding to a file in the pictures sub-directory; or a Gravatar avatar, defined by the gravatar: prefix followed by an email address (e.g. [gravatar:[email protected]]).

Immediately following a picture handle are one or more lines defining the keywords corresponding to that picture. CI-Eye intelligently scans check-in comments, scm usernames, and machine hostnames, looking for occurrences of these handles. When it discovers a match, it presents the corresponding image on the radiator.

When modifying the pictures.txt file to add a new picture (or change an existing one) a CI-Eye restart is not required. However, once CI-Eye has analysed a given build, and applied pictures to it, it will not re-analyse that build again, so your changes will take effect over a period of time -- depending on how fast and frequent your builds are.

There are two "special" picture keywords that should always be present in your pictures file: -all-green- and -doh-. These keywords correspond to the images that CI-Eye displays in the special circumstances of "all builds are green, and nothing is building" and "something catastrophic has occurred, and someone has flagged a 'doh!' moment" respectively. You can define your own pictures for these two scenarios (by changing the handle in square brackets), but you should always have an image bound to these two special keywords.

Logging

CI-Eye can log error, warning, and information messages relating to its operation. By default, warnings (and above) are logged to a rolling log file in the logs sub-directory. The configuration for CI-Eye logging is found in the logging.properties file, which initially looks like this:

handlers = java.util.logging.FileHandler
#handlers = java.util.logging.ConsoleHandler
#handlers = java.util.logging.FileHandler, java.util.logging.ConsoleHandler

.level= WARNING

java.util.logging.FileHandler.pattern = %h/.ci-eye/logs/server%u.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 3
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

java.util.logging.ConsoleHandler.level = WARNING
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

This is a standard Log4J configuration file, so you should refer to Log4J documentation for this. After changing the logging configuration file, you will need to restart the CI-Eye server before observing the effects.