Cruise Configuration Reference

<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

Attribute	Required	Description
artifactsdir	No	This directory is where Cruise will store its information, including artifacts published by jobs. The default value is 'artifacts' in the folder where the Cruise Server is installed. You can use an absolute path or a relative path which will take the server installed directory as the root. Notes: If you specify the attribute, please check whether Cruise has permission to access that directory. Also you should be aware of that changing this value while Cruise Server is running won't take effect until Cruise Server is restarted.

Examples

<cruise>
  <server artifactsdir="/var/lib/cruise/big-artifacts-folder">
    <license user="${the user name in your license}">
      ${your license key}
    </license>
  </server>
</cruise>

<license>

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

Attributes

Attribute	Required	Description
user	Yes	the user name in your license

Examples

<server artifactsdir="/var/lib/cruise/big-artifacts-folder">
  <license user="${the user name in your license}">
    ${license key}
  </license>
</server>

<security>

The <security> element can be used to enable authentication. If the element is not defined anyone can use Cruise without logging in. 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.

Examples

<server artifactsdir="/var/lib/cruise/big-artifacts-folder">
  <license user="${the user name in your license}">
    ${license key}
  </license>
  <security>
    <ldap uri="ldap://xxx.yourcompany.com"
	   managerDn="cn=Acitivity Directory LDap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
	   managerPassword="password"
	   searchBase="ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
	   searchFilter="(sAMAccountName={0})" />
  </security>
</server>

<mailhost>

The <mailhost> element is used to configure mail notifications. Mail notifications require security to be enabled.

Attributes

Attribute	Required	Description
hostname	Yes	The SMTP mail server which cruise will use to send email. For example, hostname="mailhost.yourcompany.com"
port	Yes	The mail port to use. Typically this will be the default mail port of 25.
username	Yes	The username which Cruise should use to login to the mail host.
password	Yes	The password to access the mailhost.
tls	No	Use TLS(Transport Layer Security) or not. The default value is 'false'. Use 'true' to enable TLS security.
from	Yes	Cruise will attempt to set this email address as the 'from' address for email that it sends. Note that this setting may not be honoured by the SMTP server that you use. For example, from="cruise@yourcompany.com".
admin	Yes	Cruise admintrator's email address. Cruise will send diagnostic messages to this email address. For example, Cruise will send a warning message if it is running out of disk space.

Examples

<mailhost hostname="mailhost.yourcompany.com" port="25" username="cruise" password="crs123" tls="false" from="cruise@yourcompany.com" admin="cruiseadministrator@yourcompany.com" />

<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

Attribute	Required	Description
uri	Yes	uri for the ldap server. For example, uri="ldap://ldap.yourcompany.com"
managerDn	Yes	For example, managerDn="cn=Active Directory Ldap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxxx,dc=yyyy,dc=com"
managerPassword	Yes	Cruise will connect to the LDAP server with this password
searchBase	Yes	e.g. searchBase="ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
searchFilter	No	e.g. searchFilter="(sAMAccountName={0})"

Examples

<security>
  <ldap uri="ldap://xxx.yourcompany.com"
	 managerDn="cn=Acitivity Directory LDap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
	 managerPassword="password"
	 searchBase="ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
	 searchFilter="(sAMAccountName={0})" />
  <passwordFile path="/home/cruise/admins.properties"/>
  <roles>
    <role name="cruise-admin">
      <user>Jez</user>
      <user>lqiao</user>
    </role>
  </roles>
  <admins>
    <role>cruise-admin</role>
    <user>lqiao</user>
  </admins>
</security>

<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

Attribute	Required	Description
path	Yes	The absolute path of the password file.

Examples

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

one username is Jez, the password encrypted with SHA1 is ThmbShxAtJepX80c2JY1FzOEmUk=
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

<roles>

The <roles> element is a container for roles that users defined. It can't be defined without <role>.

Examples

<security>
  ...
  <roles>
    <role name="cruise-admin">
      <user>Jez</user>
      <user>lqiao</user>
    </role>
  </roles>
</security>

<role>

The <role> element is used to define a group of users who perform similar tasks. Each user is added by adding the sub-tag <user>.

Notes:

If you want to define roles, you must define an authentication method, either <ldap> or <passwordFile>.
These roles are not associated with roles defined in LDAP; they only work within Cruise. For example, you can assign a role to the manual-approval in a stage, so that only the users in that role can approve the stage to run.

Attributes

Attribute	Required	Description
name	Yes	The name of the role.

Examples

Two users would be in the role 'pipeline-operators', they are Jez and lqiao.

<roles>
  <role name="pipeline-operators">
    <user>Jez</user>
    <user>lqiao</user>
  </role>
</roles>

<user>

One <user> element defines a particular user in a rolw. You can add as many as you like.

Notes:

The user must be in your LDAP or passwordFile.

Examples

Two users would be in the role 'pipeline-operators', they are Jez and lqiao.

<role name="pipeline-operators">
  <user>Jez</user>
  <user>lqiao</user>
</role>

<admins>

The <admins> element specifies which users are administrators. Only administrators can open the Administration tab to maintain Cruise Configuration. Administrators can perform all functions in Cruise (including triggering pipelines, deploying to environments etc.)

Notes:

The user must be in your LDAP or passwordFile.

Examples

<security>
  ...
  <admins>
    <role>cruise-admin</role>
    <user>lqiao</user>
  </admins>
</security>

<role>

One <role> element in <admins> is used to specify a group as administrators. You can add as many as you like.

Notes:

The role must refer to <roles>.

Examples

The users in role 'cruise-admin' would be administrators.

<admins>
  <role>cruise-admin</role>
  <user>lqiao</user>
</admins>

<user>

Notes:

The user must be in your LDAP or passwordFile.

Examples

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

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

<role>

Notes:

The role must be defined in <roles>.

Examples

<view>
   <user>lqiao<user>
   <role>cruise_readonly_member<role>
</view>

<pipelines>

The <pipelines> element is a container of pipelines.

Attributes

Attribute	Required	Description
group	No	The name is used to idenify a pipeline group, and must be unique. The name can contain the following characters: a-z, A-Z, 0-9, period (.), underscore (_) and hyphen (-). Spaces are not allowed. The length should be less than 255 characters. The default name is 'defaultGroup'.

Examples

<cruise>
  ...
  <pipelines group="studios">
    <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
      <materials>
	<svn url="http://your-svn/"/>
      </materials>
      <stage name="ut">
	<jobs>
	  <job name="linux">
	    <resources>
	      <resource>linux</resource>
	    </resources>
	    <tasks>
	      <ant target="unit-test" />
	    </tasks>
	  </job>
	</jobs>
      </stage>
    </pipeline>
  </pipelines>
</cruise>

<authorization>

The <authorization> tag allows you to specify the what users and roles are able to view or operate any particular group of pipelines.

<view>

The <view> element is a permission section to specify who can see the pipelines under the pipeline group. You can define roles and users in the tag.

Note:Aministrators (admins) can see all pipeline groups. Any other users or roles that are not listed under the <view> tag will be unable to see this pipeline group

Examples

Given the following configuration only administrators can operate the pipeline group, and only admins, lqiao and any users having the role 'cruise_readonly_member' can see the pipeline.

<cruise>
  ...
  <pipelines group="studios">
    <authorization>
        <view>
           <user>lqiao</user>
           <role>cruise_readonly_member</role>
        </view>
    </authorization>
    <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
    ......
    </pipeline>
  </pipelines>
</cruise>

<operate>

The <operate> element specifies who can operate the pipelines under the pipeline group. You can define roles and users.

Note:Any users/roles that are not listed under the <view> tag will be unable to see this pipeline group (even if they are listed as being allowed to <operate> that pipeline group)

Examples

Given the following configuration, only admins, lqiao, jez and the users having the role 'cruise_core_member' can operate the pipeline group. Only admins, lqiao and the users having the role 'cruise_readonly_member' can see the pipeline (jez and cruise_core_member cannot).

<cruise>
  ...
  <pipelines group="studios">
    <authorization>
        <view>
           <user>lqiao</user>
           <role>cruise_readonly_member</role>
        </view>
        <operate>
           <user>lqiao</user>
           <user>jez</user>
           <role>cruise_core_member</role>
        </operate>
    </authorization>
    <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
    ......
    </pipeline>
  </pipelines>
</cruise>

<pipeline>

The <pipeline> element specifies a single pipeline. It must be unique (including case) across the entire configuration (not only in the pipeline group).

Notes:

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

Attribute	Required	Description
name	Yes	The name is used to identify a pipeline, so each pipeline name must be unique. Pipeline name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed. Name is case-insensitive in Cruise and the length should be less than 255 characters.
labeltemplate	No	Both of material names and ${COUNT} are available in the labeltemplate and the default value of labeltemplate is '${COUNT}'. If you just specify labeltemplate="foo-1.0-${COUNT}", your pipeline will show foo-1.0-1, foo-1.0-2, and so on. When you reference material names in the labeltemplate, Cruise will use the revisions of the reference materials to populate the pipeline label. For example, given a mateial name is 'svnrepo' in a pipeline, when you specify labeltemplate="foo-1.0-${svnrepo}", then your pipeline would show foo-1.0-3123, foo-1.0-3124, and so on. Material names are case insensitive. The max length of a pipeline label is 255. If a material name is 'svnrepo', the following labeltemplates are valid: ${COUNT}, ${svnrepo}, foo-${COUNT}-${SVNrepo}, foo-${svnrepo}-${COUNT}-bar.

Examples

<pipelines>
  <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}-${svn}">
    <materials>
      <svn url="http://your-svn/" materialName="svn" />
    </materials>
    <stage name="ut">
      <jobs>
	<job name="linux">
	  <resources>
	    <resource>linux</resource>
	  </resources>
	  <tasks>
	    <ant target="unit-test" />
	  </tasks>
	</job>
      </jobs>
    </stage>
  </pipeline>
</pipelines>

<trackingtool>

The <trackingtool> element can be used to specify links to an issue tracker. Cruise will construct a link based on the commit message that you can use to take you to your tracking tool (Mingle card, JIRA issue, Trac issue etc).

Attributes

Attribute	Required	Description
link	Yes	a URL with a string '${ID}'. Cruise will replace the string '${ID}' with the first matched group value at run-time.
regex	Yes	A regex to identify the IDs. Cruise will find the first matched group in your commit messages and use it to construct the hyper-link.

Examples

Suppose you are using a Web Application to manage your tasks or bugs, and the link looks like http://your-trackingtool/yourproject/512, '512' is your task ID. Your configuration would be:

<pipeline name="yourproject">
  <trackingtool link="http://your-trackingtool/yourproject/${ID}" regex="evo-(\d+)"/>
  ...
</pipeline>

If you check in some code with a commit message which includes the characters 'evo-512' then that will appear in the modification pop-up box as a link. When you click it, Cruise will take you to the web page 'http://your-trackingtool/yourproject/512'.

For example: If you use Mingle for your task manager, the configuration would be:

<pipeline name="yourproject">
  <trackingtool link="http://your-mingle-server/projects/yourproject/cards/${ID}" regex="#(\d+)"/>
  ...
</pipeline>

Notes: You can not define multiple tracking tools in one pipeline.

<materials>

The <materials> element specifies the source of the pipeline changes. Generally this will be your codebase in your source control repository.

Notes:

Cruise supports multiple materials with the restriction that every material must contain a unique "dest" folder (that is not a subfolder of any other material). Cruise will check out the source code into this folder for each material.

Examples

<pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  <materials>
    <svn url="http://your-svn/"/>
  </materials>
  ...
</pipeline>

Multiple materials:

<pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  <materials>
    <svn url="http://your-svn/" dest="svn-folder" />
    <git url="git://127.0.0.1/precommit.git" branch="1.3branch" dest="git-folder" />
    <hg url="http://your-hg/" dest="hg-folder" />
    <p4 port="10.18.3.102:1666" username="userName" password="passwd" dest="p4-folder">
      <view><![CDATA[
	//depot/dev/src...          //anything/src/...
      ]]></view>
    </p4>
  </materials>
  ...
</pipeline>

<filter>

The <filter> element specifies files in changesets that should not trigger a pipeline automatically. When a pipeline is triggered by files that are not ignored the filtered files will still be updated with other files. You can only define one filter under each SCM material. When you trigger a pipeline manually, it will update to most recent revision, including filtered files.

Examples

<svn url="http://your-svn/">
  <filter>
    <ignore pattern="doc/**/*.*" />
  </filter>
</svn>

<ignore>

The <ignore> element is used to specify a set of files that are ignored when Cruise checks for changes. Repository changesets which only contain these files will not trigger a pipeline automatically.

Attributes

Attribute	Required	Description
pattern	Yes	defines a pattern (Ant-style) for the files to be ignored. Changes of thoes files will not trigger the pipeline. the pattern is relative to the root of the SCM repository, not the sandbox of the pipeline.

Notes

<ignore> can occur multiple times under <filter>.
The pattern is relative to the root directory of the SCM repository, not the sandbox in the agent side or the materials URL.
Ignored files are still updated when other files are updated.

Examples:

<ignore pattern="doc/**/*" />

Ignore everything under the folder 'doc'.

<ignore pattern="doc/*" />

Ignore files under the folder 'doc', excluding any subfolder.

<ignore pattern="framework/helper/*.doc" />

Ignore files that are under the directory 'framework/helper' and the file extension is .doc.

<ignore pattern="*.pdf" />

Ignore files that are under the root directory of SCM repository and the file extension is .pdf.

<ignore pattern="**/helper/*.pdf" />

Ignore all the files that is under any 'helper' folder and the file extension is .pdf.

<ignore pattern="helper/**/*.pdf" />

Ignore all the files that are in the nested directory under folder 'helper' of the repository and the file extension is .pdf.

<svn>

The <svn> element specifies the location of your code base in Subversion repository.

Attributes

Attribute	Required	Description
url	Yes	URL for the remote repository, for example: 'http://studios.thoughtworks.com/svn/myproject/trunk'. Cruise supports the following protocols for subversion: http, https, svn and svn+ssh, but does not support 'file:///'.
username	No	The user account for the remote repository.
password	No	The password for the specified user
checkexternals	No	The default value is false, the value should be either one of true/false or 1/0. 'true' or '1' means that the changes of externals will trigger the pipeline automatically.
dest	Required if there are multiple materials	The directory where the code will be checked out. This is relative to the sandbox of the Cruise Agent. Cruise prevents the destination folder from being outside the agent's sandbox.
materialName	Required if this material is referenced in pipeline labeltemplate	The name to identify a material. Material name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen, but whitespace is not allowed. A material name is case insensitive and starting with fullstop is invalid. It needs to be unique within a pipeline. The max length is 255 characters.

Notes:

Cruise cannot automatically accept svn SSL certificates. If you are using https for svn repository, you have to go to the Server and each Agent, and as the user 'cruise' do a command "svn update" to store the certificates in the cache permanently.

Examples:

For a Cruise Agent on linux with the following configuration:

<pipeline name="myproduct">
  <materials>
    <svn  url="http://cruise.thoughtworks.com/framework" dest="framwork"/>
    <svn  url="http://cruise.thoughtworks.com/componentOne" dest="mycomponent"/>
  </materials>
  ...
</pipeline>

Cruise Agent will check out source code from 'http://cruise.thoughtworks.com/framework' to '/var/lib/cruise-agent/pipelines/myproduct/framwork', and from 'http://cruise.thoughtworks.com/componentOne' to '/var/lib/cruise-agent/pipelines/myproduct/mycomponent'.

<hg>

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

Notes:

You must install Mercurial 1.0 or above on the Cruise Server and Cruise Agents for the jobs need Mercurial. Cruise does not ship with Mercurial.

Attributes

Attribute	Required	Description
url	Yes	URL to fetch source code from the Mercurial repository. If you specify the username and password for the Mercural repository, you should put them into the url.
dest	Only for multiple materials	The directory where the code will be checked out. This is relative to the sandbox of the Cruise Agent. Cruise prevents the destination folder from being outside the agent's sandbox.
materialName	Required if this material is referenced in pipeline labeltemplate	The name to identify a material. Material name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed. Material name is case insensitive. It needs to be unique within a pipeline. The max length is 255 characters.

Examples

<pipeline name="yourproject">
  <materials>
    <hg url="http://username:password@your-hg/"/>
  </materials>
  ...
</pipeline>

<p4>

The <p4> element specifies the location of your code base in a Perforce repository.

Notes:

Cruise will use directory under pipelines/{pipelineName} in agent side as Perforce root directory of perforce client workspace.

Attributes

Attribute	Required	Description
port	Yes	Perforce server connection to use (host:port). This is the same as you would pass in the p4port parameter for the p4 command line or in the P4PORT environment variable.
username	No	Perforce username to use.
password	No	Password for the specified user.
useTickets	No	Set to true to work with perforce tickets. Cruise will do a p4 login using the supplied password before each command. We recommend that you make your user a part of a p4 group, and set the ticket timeout to unlimited as described here: http://www.perforce.com/perforce/doc.current/manuals/cmdref/login.html
dest	Only for multiple materials	The directory where the code will be checked out. This is relative to the sandbox of the Cruise Agent. Cruise prevents the destination folder from being outside the agent's sandbox.
view	Yes	Valid Perforce view. The view should be a sub-element of P4. Click here to see details about VIEW of Perforce.
materialName	Required if this material is referenced in pipeline labeltemplate	The name to identify a material. Material name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed. Material name is case insensitive. It needs to be unique within a pipeline. The max length is 255 characters.

Notes:

You do not need to specify the above attributes if you have already defined them as system variables. So if you have a P4PASSWD variable defined then you can leave out the "password" tag defined above. If you already have them defined as system variables and also in Cruise configuration, Cruise will overwrite them before running p4.

Views consist of multiple mappings. Each mapping has two parts:

The left-hand side specifies one or more files in the depot and has the form: //depotname/file_specification
The right-hand side specifies one or more files in the client workspace and has the form: //clientname/file_specification

You can use anything as 'clientname' on the right-hand side in view mapping. Since Cruise needs to check out files into its own sandbox, it will its own client name automatically. The client name format is: [hostname]-[pipeline name]-[a random hash code], for example "cruise-myhostname-mypipelinename-wOaJ9kjpfgOLQCncki19ikXt5Q".

Cruise views are in the same format as that used by Perforce itself. In fact you should be able to copy a Perforce view from your existing Perforce setup and paste it into the view section.

For example:

<pipeline name="perforce-example"/>
  <materials>
    <p4 port="10.18.3.102:1666" username="userName" password="passwd">
      <view><![CDATA[
	//depot/dev/src...          //anything/src/...
	//depot/dev/test...         //anything/test/...
	//depot/dev/main/docs/...   //anything/docs/...
      ]]></view>
    </p4>
  </materials>
  ...
</pipeline>

<git>

The <git> element specifies the location of your code base in a GIT repository. Cruise only supports remote repositories.

Notes:

If 'branch' is defined, Cruise will check out the specified branch. Otherwise, Cruise will check out the master branch.

If there are submodules in the repository, Cruise will check out them as well.

You must install GIT 1.6.0.2 or above on the Cruise Server and Cruise Agents if you use http or https.

Attributes

Attribute	Required	Description
url	Yes	GIT URL for the repository.
branch	no	a branch name in the repository.
dest	Only for multiple materials	The directory under the sandbox of Cruise Agent. Cruise will check out the source code into this directory.
materialName	Required if this material is referenced in pipeline labeltemplate	The name to identify a material. Material name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed. Material name is case insensitive. It needs to be unique within a pipeline. The max length is 255 characters.

Examples are:

<pipeline name="yourproject">
  <materials>
    <git url="git://127.0.0.1/precommit.git" branch="1.3branch"/>
  </materials>
  ...
</pipeline>

<pipeline name="yourproject">
  <materials>
    <git url="http://ccegit:pst@cruiseserver.yourcompany.com/httpgit.git" />
  </materials>
  ...
</pipeline>

<pipeline>

The <pipeline> element specifies that successful completion of a stage in another pipeline will trigger the current pipeline to start.

If there are multiple pipeline dependencies, then any one of them passing will trigger a new pipeline.

Attributes

Attribute	Required	Description
pipelineName	Yes	The name of a pipeline that this pipeline depends on.
stageName	Yes	The name of a stage which will trigger this pipeline once it is successful.
materialName	Required if this material is referenced in pipeline labeltemplate	The name to identify a material. Material name can contain the following characters: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed. Material name is case insensitive. It needs to be unique within a pipeline. The max length is 255 characters.

Notes:

The downstream pipeline wouldn't be triggered if there was no passed stage in the upstream pipeline.

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="Server">
  <materials>
    <pipeline pipelineName="commonLib1" stageName="distStage"/>
    <pipeline pipelineName="commonLib2" stageName="pkgStage"/>
  </materials>
  ...
</pipeline>
<pipeline name="Client">
  <materials>
    <pipeline pipelineName="commonLib1" stageName="distStage"/>
  </materials>
  ...
</pipeline>

<stage>

The <stage> element specifies a set of jobs. If any job in a given stage fails then the stage will fail. If a stage has an <approval> configuration with manual type it can only be triggered manually (i.e. a user must click on the trigger button on the UI). If the previous stage has failed, you can still trigger the following stage manually.

Notes:

There must be at least one job in stage.

Attributes

Attribute	Required	Description
name	Yes	The name is used to identify a stage in the pipeline, so it has to be unique (case insensitive) for that <pipeline>. The available characters in stage name are following: a-z, A-Z, 0-9, fullstop, underscore and hyphen. Spaces are not allowed.

Examples

<pipeline name="yourproject">
  ...
  <stage name="ut">
    <jobs>
      <job name="linux">
	<resources>
	  <resource>linux</resource>
	</resources>
	<tasks>
	  <ant target="unit-test" />
	</tasks>
      </job>
    </jobs>
  </stage>
</pipeline>

<jobs>

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

Note:

<jobs> can contain several <job> elements. These jobs can run in parallel on different <agents>.

Examples

<stage name="ut">
  <jobs>
    <job name="linux">
      <resources>
	<resource>linux</resource>
      </resources>
      <tasks>
	<ant target="unit-test" />
      </tasks>
    </job>
  </jobs>
</stage>

<job>

A job is the basic unit of work. It is executed on an agent. A job can fetch artifacts from Cruise Server, execute tasks and publish artifacts back to Cruise Server.

A job can also be associated with a set of <resources>. Resources are used to match a Job to an Agent. An Agent can run a Job if it has all the resources that the Job specifies.

If a Job has no resources then it can be built by any Agent

Attributes

Attribute	Required	Description
name	Yes	The name of the job. The name must be unique (ignoring case) within a <stage>. The name can contain: a-z, A-Z, 0-9, fullstop, underscore and hyphen only. Spaces are not allowed.

Examples

<job name="linux">
  <resources>
    <resource>linux</resource>
  </resources>
  <tasks>
    <ant target="unit-test" />
  </tasks>
</job>

<resources>

<resources> specifies the resources needed for a job. A job can have zero or more resources.

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

Example:

<job name="linux">
  <resources>
    <resource>jdk5</resource>
    <resource>tomcat5</resource>
    <resource>mercurial</resource>
  </resources>
</job>

<resource>

A <resource> is a text tag that specifies a resource which a job requires to build. An Agent must have all the Resources specified for a Job to be able to run that Job. Resources are case-insensitive.

Example:

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

<tasks>

<tasks> specifies the tasks (like <ant>, <rake> etc) that will run as part of a job.

There can be zero or more tasks. These tasks are executed in the order specified in the configuration file. If a task fails, the subsequent tasks are not run unless they have <runif status="failed" /> defined.

The following environment variables are set for all tasks:

Variable	Description
CRUISE_SERVER_URL	The base URL for the server, including '/cruise'. For example: https://localhost:8154/cruise
CRUISE_PIPELINE_NAME	The name of the pipeline to which the job belongs to
CRUISE_PIPELINE_LABEL	The label of the pipeline to which the job belongs to
CRUISE_STAGE_NAME	The name of the stage to which the job belongs to
CRUISE_STAGE_COUNTER	The re-run counter of the stage to which the job belongs to
CRUISE_JOB_NAME	The name of the job that is being run
CRUISE_DEPENDENCY_LABEL_<upstream_pipeline_name>_<upstream_stage_name>	The label of the upstream pipeline which triggered the pipeline which the job belongs to. For example: 'CRUISE_DEPENDENCY_LABEL_FRAMEWORK_DEV' is the environment variable where the name of the upstream pipeline is 'framework' and the upstream stage is 'dev'. Hyphen ('-') is an illegal character in an environment variable. So if a pipeline name or stage name contains '-', it will be converted into an underscore. For example, ‘pipeline-foo’ with stage ‘stage-foo’ becomes: CRUISE_DEPENDENCY_LABEL_PIPELINE_FOO_STAGE_FOO.

Examples

<job name="linux">
  <tasks>
    <ant target="unit-test" />
  </tasks>
</job>

<ant>

Specifies an Ant build to run. Ant is assumed to be present from the command line on the agent. Cruise depends on and uses JDK 1.6. If JDK 1.4 or 1.5 binaries are required by a build, it can be specified in the Ant javac task.

All paths specified are relative to the pipeline working directory.

Attributes

Attribute	Required	Description
buildfile	No	Path to Ant build file. If not specified, the path defaults to 'build.xml'.
target	No	Ant target(s) to run. If not specified, the target defaults to 'default'
workingdir	No	The directory from where Ant is invoked

Examples

Invoke Ant, specifying a set of targets to run:

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

Invoke Ant in a specific working directory with a set of targets:

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

<exec>

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

All paths specified are relative to the pipeline working directory.

Attributes

Attribute	Required	Description
command	Yes	The command or script to be executed, relative to the working directory
args	No	Set of arguments (as a single string) to be passed to the command or script. Note that for complex or quoted arguments we suggest that you use separate <arg> tags for each argument.
workingdir	No	The directory in which the script or command is to be executed

Examples

Invoke ruby, specifying the working directory as workspace/codebase and executing the ruby script backup.rb.
```
<tasks>
  <exec command="/usr/local/bin/ruby" args="backup.rb" workingdir="workspace/codebase"/>
</tasks>
```

<arg>

Specify a single argument for exec command.

This element is optional and can occur multiple times. It serves as an alternative to the "args" attribute of exec, but it allows the use of any character required for making argument. For example, you can specify double quote using the xml escaped format: "

Note:When running commands on Windows, Cruise won't launch your command with system shell (cmd.exe), so you can't use shell commands (like echo) directly. If you want, you can pass your shell command as arguments to the cmd.exe.

On Windows you should specify the full name of your script file such as "mybuild.bat". (Only specifying "mybuild" won't work)

Attributes

Attribute	Required	Description
value	Yes	A single argument to be passed to the exec command.

Examples

Echo something on Windows:

<exec command="cmd">
  <arg value="/c"/>
  <arg value="echo"/>
  <arg value="something to print out"/>
</exec>

Run command with pipe character in arguments:

<exec command="MsBuild">
  <arg value="D:\projects\project\project-8.sln"/>
  <arg value="/REBUILD"/>
  <arg value="/CFG=&quot;Release_99|Win32&quot;"/>
</exec>

<nant>

Specifies a NAnt build to run. NAnt is assumed to be present from the command line on the agent.

All paths specified must be relative to the pipeline working directory.

Attributes

Attribute	Required	Description
buildfile	No	Path to NAnt build file. If not specified, the path defaults to 'default.build'. The path is relative to the sandbox directory and cannot be outside the sandbox.
target	No	NAnt target(s) to run. If not specified, defaults to the default target of the build file.
workingdir	No	The directory from where NAnt is invoked
nantpath	No	Path of the directory in which NAnt is installed. By default Cruise will assume that NAnt is in the system environment variable ${PATH}. If the path is specified, then the path must be the same in all agents which run the job.

Examples

Invoke NAnt, specifying a set of targets to run:

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

<rake>

Specifies a Rake build to be run. Ruby and Rake are assumed to be present from the command line on the agent.

All paths specified must be relative to the pipeline working directory.

Attributes

Attribute	Required	Description
buildfile	No	Path to Rake file. If not specified, the path defaults to 'rakefile'. The path cannot start from '.'
target	No	Rake target(s) to run. If not specified, defaults to the default target of the build file
workingdir	No	The directory from where Rake is invoked

Examples

Invoke rake, specifying a set of targets to run:

<tasks>
  <rake buildfile="rakefile" target="smoke-test"/>
</tasks>

<fetchartifact>

Fetch artifacts from previous stages in the same pipeline or stages of upstream pipelines that this pipeline depends on.

All paths specified are relative to the pipeline working directory.

Attributes

Attribute	Required	Description
pipeline	No	The name of upstream pipeline on which the pipeline of the job depends on. The pipeline should be added as a dependency under <materials>. Defaults to current pipeline if not specified.
stage	Yes	The name of the stage to fetch artifacts from
job	Yes	The name of the job to fetch artifacts from
srcdir	One of	The path of the artifact directory of a specific job, relative to the sandbox directory. If the directory does not exist, the job is failed
srcfile	One of	The path of the artifact file of a specific job. Note: If the file does not exist, the job will fail. Cruise will not fetch the artifact again if it has not changed. The directory path is relative to the pipeline working directory.
dest	No	The path of the directory where the artifact is fetched to. The directory is overwritten if it already exists. The directory path is relative to the pipeline working directory.

Example:

Fetch all artifacts in the directory 'pkg' from the previous stage in the same pipeline and put them under the directory 'lib'

<pipelines>
  <pipeline name="cruise">
    ...
    <stage name="dev">
      <jobs>
	<job name="unit">
	  <artifacts>
	    <artifact src="target/deployable.jar" dest="pkg"/>
	  </artifacts>
	</job>
      </jobs>
    </stage>
    <stage name="ft">
      <jobs>
	<job name="functional">
	  <tasks>
	    <fetchartifact stage="dev" job="unit" srcdir="pkg" dest="lib"/>
	  </tasks>
	</job>
      </jobs>
    </stage>
  </pipeline>
</pipelines>

Fetch a single artifact from a stage in the upstream pipeline 'framework' and put it under the directory 'lib'

<pipeline name="cruise">
  <materials>
    <pipeline name="framework" stage="ft"/>
  </materials>
  <stage name="dev">
    <jobs>
      <job name="unit">
	<tasks>
	  <fetchartifact pipeline="framework" stage="dev" job="unit"
			 srcfile="pkg/deployable.jar" dest="lib" />
	</tasks>
      </job>
    </jobs>
  </stage>
</pipeline>

<runif>

Specifies when a task should be allowed to run. Multiple conditions may be defined for each task.

A running job on an agent has two possible states: passed or failed. A job starts in the state “passed”. If any task fails, it transitions to the state “failed”.

A task can specify any of three possible runif filters: 'passed', 'failed' or 'any'. (‘passed’ is the default)

Attributes

Attribute	Required	Description
status	Yes	The status is the job's current status. The value should be one of 'passed', 'failed' or 'any'.

Notes:

If <runif> is under <exec> while the <exec> has some <arg>s, the <runif>s should be defined before <arg>, e.g.

    <exec command="echo">
       <runif status="passed" />
       <arg value="test" />
    </exec>

Examples

Given the tasks in a job is following:

<tasks>
    <ant  buildfile="build.xml" target="complie-test-source"/>
    <fetchartifact  pipeline="cruise" stage="dist" job="package-artifact" srcdir="pkg">
       <runif  status="passed"/>
    </fetchartifact>
    <exec command="./copy_error_log_to_someplace" >
       <runif status="failed"/>
    </exec>
</tasks>

Scenario one:

If task 1 <ant> passed, task 2 <fetchartifact> would be executed.

If task 2 <fetchartifact> passed, task 3 <exec> would NOT be executed.

If task 2 <fetchartifact> failed, task 3 <exec> would be executed.

Scenario two:

If task 1 <ant> failed, task 2 <fetchartifact> would NOT be executed.

Instead, task 3 <exec> would be executed.

<oncancel>

Specifies a task to execute when a stage is cancelled. Only one task can be defined in <oncancel>.

If a job is cancelled during the assigning phase, the job will not start preparing
If a job is cancelled during the preparing phase, preparing will complete, but no tasks will be executed
If a job is cancelled during the building phase:

If the currently running task does not have <oncancel> defined, the task will complete and no other tasks will execute
If the currently running task does have <oncancel> defined, the task defined within <oncancel> will execute immediately. As soon as both the original task and the <oncancel> task are completed, no other tasks will execute

If a job is cancelled during the completing phase, the agent will ignore the request and complete as planned

Examples

The task 'start_server' starts a process on an agent. When the stage is cancelled, the agent will invoke the cancel task 'kill_server' to kill the process early and clean up any extra files.

<tasks>
  <ant target="start_server">
    <oncancel>
      <ant target="kill_server" />
    </oncancel>
  </ant>
</tasks>

<artifacts>

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

Examples

<job name="unit">
  <artifacts>
    <artifact src="target/deployable.jar" dest="pkg"/>
    <test src="target/junit-output" dest="junit"/>
  </artifacts>
</job>

<artifact>

Publish build artifacts to the artifact repository for the job.

Attributes

Attribute	Required	Description
src	Yes	The file or folders to publish to the server. Cruise will only upload files that are in the working directory of the job. You can use wildcards to specify the files and folders to upload: ** means any path, * means any file or folder name.
dest	No	The destination is relative to the artifacts folder of the current instance on the server side. If it is not specified, the artifact will be stored in the root of the artifacts directory.

You can use wildcards to specify which files to upload. The wildcard syntax follows the commonly used ant/nant style. So "target/**/*.xml" would upload all xml files in the target directory and any of its subdirectories. The original directory structure is preserved on the server.

Examples

<job name="unit">
  <artifacts>
    <artifact src="target/deployable.jar" dest="pkg"/>
  </artifacts>
</job>

<job name="unit">
  <artifacts>
    <artifact src="target/**/*Test.xml" dest="pkg"/>
  </artifacts>
</job>

The following will upload all xml files to the server's artifact repository.

<job name="unit">
  <artifacts>
    <artifact src="target/**/*.xml" />
  </artifacts>
</job>

<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

Attribute	Required	Description
src	Yes	Specify the directory into which the test output of the job will be put on agent side. This is relative to the Job's working directory.
dest	No	The path in the artifacts repository where the reports will be placed.

Examples

<job name="unit">
  <artifacts>
    <test src="target/junit-output" dest="junit"/>
  </artifacts>
</job>

<tabs>

The <tabs> element allows you to add tabs to the Job Details page. You can put any artifact that can be rendered by a web browser into a tab. For example, if your coverage tool produces an html report, you can easily place that report into a tab. Tabs are implemented as iframes (see W3C iframe definition ).

Example:

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

<tab>

Define a tab with specific name and artifact to show.

Attributes

Attribute	Required	Description
name	Yes	The name of the tab. If should be unique in that job.
path	Yes	The relative path of a file in the artifact repository of the job.

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.

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

<property>

Define a Property based on the contents of an XML file.

Attributes

Attribute	Required	Description
name	Yes	The name of the property. It has to be unique within a <job>. The name can contain: a-z, A-Z, 0-9, fullstop, underscore and hyphen only. Spaces are not allowed. Name is case-sensitive.
src	Yes	The xml file containing the data that you want to use to create the property, and it isn't allowed to start from '.' Properties are set on the Agent at the end of the build and does not need to be an artifact that will be uploaded to the server.
xpath	Yes	The XPath that will be used to create the property.

Example:

This is a simple example to parse the errors and failures count from a single junit file and turn them into properties.

<job name="junit">
  <tasks>
    <ant target="unittest">
  </tasks>
  <properties>
    <property name="junit.errors" src="target/junit-reports/TEST-MainAppTest.xml" xpath="string(/testsuite/@errors)" />
    <property name="junit.failures" src="target/junit-reports/TEST-MainAppTest.xml" xpath="string(/testsuite/@failures)" />
  </properties> 
</job>

Here's a more complex example. This will parse the class, method, block, and line coverage out of an EMMA coverage.xml file.

<job name="emma">
  <artifacts>
    <artifact src="target/emma" dest="analysis" />
  </artifacts> 
  <tasks>
    <ant target="emma">
  </tasks>
  <properties>
    <property name="coverage.class" src="target/emma/coverage.xml" xpath="substring-before(//report/data/all/coverage[starts-with(@type,'class')]/@value, '%')" />
    <property name="coverage.method" src="target/emma/coverage.xml" xpath="substring-before(//report/data/all/coverage[starts-with(@type,'method')]/@value, '%')" />
    <property name="coverage.block" src="target/emma/coverage.xml" xpath="substring-before(//report/data/all/coverage[starts-with(@type,'block')]/@value, '%')" />
    <property name="coverage.line" src="target/emma/coverage.xml" xpath="substring-before(//report/data/all/coverage[starts-with(@type,'line')]/@value, '%')" />
  </properties> 
</job>

<approval>

Specifies how a stage should be triggered. An <approval> of type 'manual' can be used to stop a pipeline execution at the start of a stage and can only be resumed when it is manually approved on the pipeline activity page or through RESTful url.

Attributes

Attribute	Required	Description
type	Yes	Either 'manual' or 'success'. 'manual' means the stage needs to be approved manually. 'success' means the stage will be automatically triggered when the previous stage passes.

Notes:

<approval> must be the first sub-element of <stage>.
If an approval is not specified then the behavior is same as 'success' i.e. the stage will be automatically triggered when the previous stage passes.

Example:

<stage name="ut">
  <approval type="manual" />
  ...
</stage>

<authorization>

You can use <authorization> under an <approval> with a 'manual' type to specify who can approve this stage. There are two sub-elements: <user> and <role>.

Examples

<approval type="manual">
  <authorization>
    <user>lqiao</user>
    <role>cruise_admins</role>
  </authorization>
</approval>

Notes:

The <authorization> configuration under <appoval> only applies for a "manual" approval.

<agents>

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

Notes:

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

Attribute	Required	Description
hostname	Yes	Hostname for the agent
ipaddress	Yes	IP for the agent.
uuid	Yes	Identifier for the agent. It is created by Cruise automatically.
isDenied	No	The values should be one of 'true' or 'false' (or 1 / 0). 'true' or '1' means that the agent is denied. Cruise doesn't assign jobs to a denied agent.

Notes:

A local agent will be approved automatically.

<resources>

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

Note:

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.

Examples

<agents>
  <agent hostname="agent01" ipaddress="192.168.0.1" uuid="94fcb7ad-8b97-4078-b5f6-3c7436d6a390">
    <resources>
      <resource>java</resource>
      <resource>linux</resource>
    </resources>
  </agent>
</agents>

Cruise Configuration Reference

Configuration reference

<cruise>

<server>

Attributes

Examples

<license>

Attributes

Examples

<security>

Examples

<mailhost>

Attributes

Examples

<ldap>

Attributes

Examples

<passwordFile>

Attributes

Examples

<roles>

Examples

<role>

Attributes

Examples

<user>

Examples

<admins>

Examples

<role>

Examples

<user>

Examples

<role>

Examples

<pipelines>

Attributes

Examples

<authorization>

<view>

Examples

<operate>

Examples

<pipeline>

Attributes

Examples

<trackingtool>

Attributes

Examples

<materials>

Examples

<filter>

Examples

<ignore>

Attributes

Notes

Examples:

<svn>

Attributes

Notes:

Examples:

<hg>

Notes:

Attributes

Examples

<p4>

Notes:

Attributes

Notes:

<git>

Notes:

Attributes

Examples are:

<pipeline>

Attributes

Notes:

Examples

<stage>

Attributes

Examples