Help documentation

Cruise integration

RESTful API

Files in the artifact repository and properties can be created and accessed through a simple web API. You can point your browser at the URLs we give here. Most build tools like ant, nant and rake have tasks for accessing http URIs. You could use the free open-source tool cURL which is available on most operating systems.

Uploading and downloading files

Files can be downloaded from the artifacts repository using a URL that follows the following pattern:

http://[Cruise Server host]:8153/cruise/files/[Pipeline name]/[Pipeline label]/[Stage name]/[Job name]/[Path to file]

So for example on the page below:

you would download framework.zip with the following URL:

http://[Cruise Server host]:8153/cruise/files/framework/1.0.1154/dist/binaries/pkg/framework.zip

Instead of an actual label, there is a "special" label you can use: latest .

  • latest gives you artifacts from the most recently scheduled job, whether it is scheduled, building, passed or failed.

Other formats

Creating properties and retrieving their value

You can get properties using the following URL (note that copying and pasting the text present at the place highlighted in red above gets you part of the URL here):

http://[Cruise Server host]:8153/cruise/properties/[Pipeline name]/[Pipeline label]/[Stage name]/[Stage Counter]/[Job name]

Using RESTful APIs with authentication

If you have authentication turned on, access to the RESTful URLs will be restricted in exactly the same way as any other page on the application. If you're using a script, it's not very helpful to be redirected to a log in page. Instead, you can use HTTP Basic authentication to supply valid credentials to Cruise.

You can get properties in CSV formant using the following CURL command:

curl -u [username]:[password] http://[Cruise Server host]:8153/cruise/properties/[Pipeline name]/[Pipeline label]/[Stage name]/[Stage Counter]/[Job name]

Getting information in your build scripts

Cruise sets the following environment variables for all builds it executes:

  • CRUISE_SERVER_URL -- the base URL for the server. This includes the /cruise - so it would look something like this: https://[Cruise Server host]:8154/cruise
  • CRUISE_PIPELINE_LABEL -- the label for the current pipeline for the server. By default this is set to the pipeline count. You can customise this in the pipeline configuration by setting a labeltemplate.
  • CRUISE_PIPELINE_NAME -- the name of the pipeline that is being run
  • CRUISE_STAGE_NAME -- the name of the stage that is being run
  • CRUISE_STAGE_COUNTER -- the time of the stage run.
  • CRUISE_JOB_NAME -- the name of the job that is being run
  • CRUISE_DEPENDENCY_LABEL_${PIPELINE_NAME}_${STAGE_NAME} -- the label of the upstream pipeline available on the agent as an environment variable.

You can access these environment variables to construct versioned artifacts or to store properties on the current build. For example the following snippet of an ant file shows how to access cruise variables:

<property environment="cruise" />
<target name="all">
    <echo message="Building all!" />
    <echo message="CRUISE_SERVER_URL: ${cruise.CRUISE_SERVER_URL}" />
    <echo message="CRUISE_PIPELINE_NAME: ${cruise.CRUISE_PIPELINE_NAME}" />
    <echo message="CRUISE_PIPELINE_LABEL: ${cruise.CRUISE_PIPELINE_LABEL}" />
    <echo message="CRUISE_STAGE_NAME: ${cruise.CRUISE_STAGE_NAME}" />
    <echo message="CRUISE_STAGE_COUNTER: ${cruise.CRUISE_STAGE_COUNTER}" />
    <echo message="CRUISE_JOB_NAME: ${cruise.CRUISE_JOB_NAME}" />
</target>

Integrating artifacts in tabs

Cruise allows you to create a new tab containing any artifact that your browser can display. This might include html or text pages, images or even PDF and video files.

Cruise embeds the artifact in an IFrame, so even html pages with frameset navigation work well. The following shows an example of a JUnit test report embedded into a tab in cruise:

<tabs>
    <tab name="Test_Overview" path="/test-reports/html/index.html" />
</tabs>

This creates a Test_Overview tab in the job details page:

Integration with bug tracking and story management tools

Cruise allows you to link your commit messages with bug tracking and story management tools which are web applications.

For example, the following shows an example of a tracking cards on Mingle by card number in cruise:

<pipeline name="mypipeline">
    <trackingtool link="http://mingle.thoughtworks.com/cruise/${ID}" regex="#(\d+)"/>
</pipeline>

Given a user commit codes with comments like 'fix bug #2309 by adding validator class.', when cruise detects the modifications, you will see:

Monitoring your builds with client tools

Cruise allows you to monitor your builds with CCTray through the url 'http://[your_cruise_server]:8153/cruise/cctray.xml.

If you have switched on security in your configuration you can use BASIC authentication to connect. In many cases you can do this by including the username and password in the URL. The username and password should not include special characters.

For example:

 http://[username]:[password]@[your_cruise_server]:8153/cruise/cctray.xml

CCtray does not currently support basic authentication. Cruise will return 'building' state as 'passed' state to CCTray when the stage or job is building for the first time i.e. without history.