<cruise>

The <cruise> element is the root element of the configuration.

<server>

The <server> element can be used to define information and attributes of the cruise server.

Attributes

<license>

The <license> element contains your Cruise license. If you don't have one please visit the Cruise Website to obtain one.

Attributes

Examples

<license user="${the user name in your license}">
  ${license key}
</license>
          

<security>

The <security> element can be used to enable authentication. If the element is not there, authentication will be disabled. We currently support LDAP and a simple password file format. You can use both methods if you want. This can be useful if you want to allow access from scripts without having to add a lot of users to your corporate LDAP. In this case you could add a 'script' user to the password file.

<ldap>

The <ldap> element is used to specify the ldap server. Users can access Cruise with their username and password from this ldap server.

Attributes

<passwordFile>

The <passwordFile> element is used to specify a file which has a set of Username and password pairs. The format of username and password in this file is ${username}=${password which has been encrypted with SHA1}, with one line per user.

Attributes

Examples

Suppose the password file is admins.properties, which is located in /home/cruise. You want to create two users as Administrators:

1. one username is Jez, the password encrypted with SHA1 is ThmbShxAtJepX80c2JY1FzOEmUk=
2. the other one is lqiao, the password encrypted with SHA1 is TfkgShslgJepX80c2JY1trwEskT=

The configuration could look like:

<security>
  <passwordFile path="/home/cruise/admins.properties"/>
</security>
          

The username and password could be set in admins.properties as follows:

            Jez=ThmbShxAtJepX80c2JY1FzOEmUk
            lqiao=TfkgShslgJepX80c2JY1trwEskT
          

<admins>

The <admins> element specifies which users are administrators. Only administrators can open the Administration tab to maintain Cruise Configuration.

If you want to specify administrators, you must define an authentication method, either <ldap> or <passwordFile>.

<user>

One <user> element is used to specify one administrator. You can add as many as you like.

1. The user must be in your LDAP or passwordFile.
2. Cruise does not support groups yet.
3. If the same user name exists in both the LDAP and password file, then both of them would be administrators.

Examples

Two users would be administrators, they are Jez and lqiao.

<admins>
  <user>Jez</user>
  <user>lqiao</user>
</admins>
          

<pipelines>

The <pipelines> element is a container of pipelines.

<pipeline>

The <pipeline> element specifies a single pipeline.

There should be at least one stage in one pipeline. Cruise uses the pipeline name to identify the pipeline. If you change the pipeline name, you will lose the history of the pipeline.

Attributes

<dependencies>

The <dependencies> element specifies stages that can trigger this pipeline. If multiple dependencies are defined the pipeline will trigger on successful completion of any of them.

<depends>

The <depends> element specifies the stage of a pipeline which will trigger the current pipeline to start.

Attributes

Examples

Suppose there are four pipelines, and they are commonLib1, commonLib2, Server and Client. For example, the stage 'distStage' in commonLib1 pipeline can trigger the other two pipelines, and the stage 'pkgstage' in commonLib2 pipeline can trigger Server pipeline. The configuration would be:

<pipeline name="commonLib1">
      ...
  <stage name="unittest">
       ...
  </stage>
  <stage name="distStage">
       ...
  </stage>
  <stage name="publishStage">
       ...
  </stage>
<pipeline name="commonLib1">
      ...
  <stage name="unittest">
       ...
  </stage>
  <stage name="functionaltest">
       ...
  </stage>
  <stage name="pkgStage">
       ...
  </stage>
</pipeline>
<pipeline name="Server">
  <dependencies>
    <depends pipeline="commonLib1" stage="distStage"/>
    <depends pipeline="commonLib2" stage="pkgStage"/>
  </dependencies>
       ...
</pipeline>
<pipeline name="Client">
  <dependencies>
    <depends pipeline="commonLib1" stage="distStage"/>
  </dependencies>
       ...
</pipeline>
      

<stage>

The <stage> element specifies a set of jobs. Any jobs in a given stage failed means the stage failed. If a stage without <approval> is followed passes any following stages will be triggered automatically.

There must be at least one job in one stage.

Attributes

<materials>

The <materials> element specifies the source of the pipelines changes. Generally this will be your codebase in your source control repository. Cruise will check modifications and check out your code by this material.

Currently Cruise does not support multiple materials in one pipeline. so you can specify only one material, either subversion or mercurial. Cruise checks modifications every 1 minute. You can not currently specify the interval for checking modifications.

<svn>

The <svn> element specifies the location of your code base in Subversion repository. Cruise only supports remote repository. Note that you do not have to check out the code manually. Cruise supports the following protocols for subversion: http, https, svn and svn+ssh.

Notes:

You do not have to install Subversion in Cruise server and agent. But if you use https, you have to go to the server and each agent, and as the user 'cruise', do an svn up to store the certificates in the cache permanently.

Attributes

<hg>

The <hg> element specifies the location of your code base in a Mercural repository. Cruise supports remote repository. Cruise supports two protocols for mercural: http and ssh.

Notes:

You must install Mercurial 1.0 or above on the Cruise server and agents which will be assigned a job with Mercurial repository to run. Cruise does not Ship with Mercurial.

Attributes

<jobs>

The <jobs> element specified the set of jobs for a stage.

<jobs> can contain several <job> elements; these jobs can run in parallel on different agents individually (see the <agent> element).

<job>

A <job> is the basic unit of work — it will be sent to an agent to build. The agent will update the source code, fetch the artifacts which have been defined in <job>, build and publish the results of your job.

Notes:

If you want a particular job to be able to be executed on a particulare agent, you have to specify <resources>. If so, Cruise will assign it to the agent which have those resources to supply.

Attributes

<resources>

<resources> specifies the resources needed for a job.

If a job has no resources it can be built on any available agent.

<resource>

A <resource> is the declaration of a resource which the job require to build.

contents

The available characters for resources are following: a-z, A-Z, 0-9, fullstop, underscore and hyphen. The name is case-insensitive in Cruise. Spaces are not allowed.

You can add multiple resources for one job. An agent must have all of resources in a job for the agent to build that job.

Example:

<resources>
  <resource>jdk5</resource>
  <resoucre>tomcat5</resource>
  <resoucre>mercurial</resource>
</resources>
          

<tasks>

<tasks> specifies the tasks that will run as part of a job. The following environment variables are set for all tasks:

You can add multiple tasks. All of tasks will execute in the order specified in the configuration file. If a task fails, the following tasks would never run. Note that while you can specify multiple tasks, it is usually better to only have a single task. Consider making each of those tasks a separate job, or creating a build target that specifies the multiple targets.

All paths specified below must be relative to the base directory of your materials.

<ant>

Specifies an Ant build to run. Cruise ships with apache-ant-1.7.0 and will use that version to run the build script. Cruise also depends on and uses JDK 1.6. If you require 1.4 or 1.5 binaries, please remember to specify this in your Ant javac task.

Attributes

Examples

1. Invoke ant, specifying a set of targets to run:

   <ant target="-Drun=all clean.ivy.localivy clean ft.long_running" />
             

2. Invoke ant in a specific working directory with a specific set of targets:

   <ant workingdir="build" buildfile="mybuild.xml" target="-Drun=all clean.ivy.localivy clean ft.long_running" />
             

<exec>

Runs a specified command. The build will fail if the command cannot be run or it returns an error.

Attributes

Examples

1. Invoke ruby, specifying the working directory as /workspace/MyCodebase and executing the ruby script backup.rb.

   <tasks>
     <exec workingdir="/workspace/MyCodebase"  
                command="/usr/local/bin/ruby"
                args="backup.rb"/>
   </tasks>
             

<nant>

Specifies a NAnt build to be run. Cruise does not include a copy of Nant so you should install it on the agent yourself.

Attributes

Examples

1. Invoke nant, specifying a set of targets to run:

   <nant buildfile="myproject.build" target="smoke-test" />          
   

<rake>

Specifies a Rake build to be run. Cruise does not include rake so you have to install it on those agents which will do the job.

Attributes

<artifacts>

<artifacts> specifies what files the agent will publish to the server.

<artifact>

Publish build artifacts to the artifact repository for the job.

Attributes

<test>

The src attribute should point towards a folder that contains the test output files. Cruise will use these to generate a test report. Test information is placed in the Failures and Test sub-tabs. Test results from multiple jobs are aggregated on the stage detail pages. This allows you to see the results of tests from both functional and unit tests even if they are run in different jobs.

Attributes

<tabs>

The <tabs> element allows you to add tabs to the Job Details page. You can put any artifact into a tab. For example, if your coverage tool produces an html report, you can easily place that report into a tab.

<tab>

Define a tab specific name and and artifact to show.

Attributes

Example:

Given some coverage infomation in 'target/Jcoverage' folder on the agent side, We configure a tab to show the coverage information by specifying a tab with the index.html file.

<artifacts>
    <artifact src="target/jcoverage" dest="Jcoverage">
</artifacts> 
<tabs>
    <tab src="coverage" path="Jcoverage/index.html">
</tabs> 
    

<approval>

You can use <approval> to specify that the pipeine should pause for manual approval when this stage completes. If there is no <approval>, the following stage will be run automatically once the stage is passed.

<approval> must be the last subelement in <stage>

<agents>

The <agents> element specifies the set of agents known by the server.

Do not change it manually. You can manage these through the Agents tab.

<agent>

An approved agent. Before it is approved, the agent is displayed on the top of the agent tab with a grey bar.

Attributes

Notes:

Cruise uses the agent's hostname as its identification.

A local agent will be approved automatically.

<resources>

<resources> descibes the resources available on a particular agent.

An agent without any resources will build any jobs that don't specify resources. Refer to the <resources> of <job>.

<resource>

resources names can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed.