Cruise is configured using an XML configuration file. This file can be edited through the Cruise Server dashboard. Cruise allows you to edit sections of the configuration independently and will check the syntax of the configuration before it saves it again. You can also edit the full XML file if you wish, by clicking on the Source XML section of the Administration tab.
Creating a new pipeline
To create a new pipeline, go to the Pipelines configuration section of the Administration tab and click on the "Add new pipeline" link at the top right of the page.
Creating a new stage
Add a stage to a pipeline to run jobs that should only run when the previous stage passes. You might do this, say, to move out jobs that would would make a stage slow, if the jobs depend on artifacts created during a previous stage etc.
To create a new stage, go to the Pipelines configuration section of the Administration tab and edit the pipeline that you want to add the new stage to:
Add jobs to a stage
Add jobs to a stage to run several pieces of work in parallel on your grid. When a stage is triggered, all the jobs in that stage will be scheduled. All the jobs in a stage run concurrently - one job per agent. If there are not enough Agents to run all the jobs, those jobs will be queued until an agent becomes free.
When you create your first Pipeline Cruise will create a default Stage (called "defaultStage") with a single default job (called "defaultJob"). You can add more jobs to this stage. You might do this to, say, generate different artifacts, run the build on different operating system etc.
To add a job to a stage, go to the Pipelines configuration section of the Administration tab and edit the stage that you want to add a job to:
You can copy an existing job, or you can add a new one. The new job will appear the next time a pipeline builds. You may want to force the build to see the changes that you have made.
Here is a sample configuration for a simple stage:
<stage name="documentation"> <jobs> <job name="javadoc"> <artifacts> <artifact src="xstream/target/javadoc" dest="output" /> </artifacts> <tasks> <ant buildfile="xstream/build.xml" target="javadoc" /> </tasks> <tabs> <tab name="Javadoc" path="output/javadoc/index.html" /> </tabs> </job> </jobs> </stage>
To keep the build as fast as possible, you should try and keep all the jobs in a stage about the same length of time. If one of the jobs is significantly longer than the others, then the next stage in the pipeline will be delayed. You should move the long job out into a new stage.
For more information on jobs and the tasks that can be executed within them, please see jobs section of the Configuration reference
Stage Approvals in action
By default, when one stage completes successfully, the next stage is automatically triggered by Cruise. However sometimes you don't want the next stage to be triggered automatically. This might be the case if you have a stage that deploys your application to a testing, staging or production environment. Another case can be when you don't want your pipeline to be automatically triggered by changes in version control. In these situations, you want the stage triggered by manual intervention. This can be done through manual approvals.
To define a manual approval, you'll need to go to the Administration tab, select the stage which you want to be triggered only by a manual approval, and then add the following configuration.
<stage name="uat"> <approval type="manual"/> . . . </stage>
If you add a manual approval to the first stage in a pipeline, it will prevent the pipeline from being triggered from version control. Instead, it will only pick up changes when you trigger the pipeline manually (this is sometimes known as "forcing the build").
From Cruise 1.1, you can control who can trigger manual approvals. See the section on security for more details.