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.

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 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

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.