Project Configuration Block¶
A <project> block defines all the configuration for one project running in a CruiseControl.NET server.
Version¶
Available from version 1.0
Examples¶
Minimalist example
1<project name="Project 1" />Full Example
1<project name="Project 1" queue="Q1" queuePriority="1">
2 <workingDirectory>yourWorkingDirectory</workingDirectory>
3 <artifactDirectory>yourArtifactDirectory</artifactDirectory>
4 <category>Category 1</category>
5 <webURL>http://server1/ccnet/server/local/project/testProject/ViewLatestBuildReport.aspx</webURL>
6 <modificationDelaySeconds>2</modificationDelaySeconds>
7 <maxSourceControlRetries>5</maxSourceControlRetries>
8 <initialState>Stopped</initialState>
9 <startupMode>UseInitialState</startupMode>
10 <triggers>
11 <!--yourFirstTriggerType .. -->
12 <!--yourOtherTriggerType .. -->
13 </triggers>
14 <!-- state type="yourStateManagerType" .. -->
15 <!-- sourcecontrol type="yourSourceControlType" .. -->
16 <!-- labeller type="yourLabellerType" .. -->
17 <prebuild>
18 <!-- yourFirstPrebuildTask .. -->
19 <!-- yourOtherPrebuildTask .. -->
20 </prebuild>
21 <tasks>
22 <!-- yourFirstTask .. -->
23 <!-- yourOtherTask .. -->
24 </tasks>
25 <publishers>
26 <!-- yourFirstPublisherTask .. -->
27 <!-- yourOtherPublisherTask .. -->
28 </publishers>
29 <externalLinks>
30 <externalLink name="My First Link" url="http://somewhere/" />
31 <externalLink name="My Other Link" url="http://somewhere.else/" />
32 </externalLinks>
33 <parameters>
34 <textParameter name="Build Name" default="Unknown" />
35 </parameters>
36 <linkedSites>
37 <namedValue name="ohloh" value="5623" />
38 </linkedSites>
39</project>Configuration Elements¶
| Element | Description | Type | Required | Default | Version |
| askForForceBuildReason | Should a reason be requested when a force build is triggered. | String - one of: * None * Optional * Required |
No | None | 1.5 |
| category | A general category for this project. This is used by the dashboard to provide groupings to the project. Categories do not span servers. | String | No | None | 1.0 |
| artifactDirectory | The Artifact Directory for the project (this is used by other blocks). Relative paths are relative to a directory called the project Name in the directory where the CruiseControl.NET server was launched from. The Artifact Directory is meant to be a persistence location for anything you want saved from the results of the build, e.g. build logs, distributables, etc. Make sure this folder us unique per project to prevent problems with reporting about a build. You don't need to quote the Aftifact Directory, even if it contains spaces. | String | No | Artifacts | 1.0 |
| workingDirectory | The Working Directory for the project (this is used by other blocks). Relative paths are relative to a directory called the project Name in the directory where the CruiseControl.NET server was launched from. The Working Directory is meant to contain the checked out version of the project under integration. Make sure this folder us unique per project to prevent problems with the build. You don't need to quote the Working Directory, even if it contains spaces. | String | No | WorkingDirectory | 1.0 |
| data | A data store for project information. | IDataStore | No | none | 1.6 |
| description | An optional description of the project. | String | No | None | 1.0 |
| externalLinks | Each of these are used to display project related links on the project report page of the Web Dashboard, and are meant as a convenient shortcut to project-related web sites outside of CruiseControl.NET. | External Links array | No | None | 1.0 |
| impersonation | An optional impersonation account. This is only available on Windows OSs. |
Impersonation | No | None | 1.5 |
| initialState | Sets the state of the project when CCNet service/Console starts. Stopped can be handy when you are adding a lot of projects which are depending on other projects (via the project trigger) and these may not be build right away. This value is only used when startupMode is set to UseInitialState. | String - one of: * Started * Stopped |
No | Started | 1.5 |
| labeller | Labellers are used to generate the label that CCNet uses to identify the specific build. The label generated by CCNet can be used to version your assemblies or label your version control system with each build. | Labeller Blocks | No | Default Labeller | 1.0 |
| linkedSites | Links for this project to other sites. Example for the Ohloh Project plugin<linkedSites><namedValue name="ohloh" value="5623"/></linkedSites> | Named Value array | No | None | 1.5 |
| maxSourceControlRetries | The maximum amount of source control exceptions in a row that may occur, before the project goes to the stopped state(when StopProjectOnReachingMaxSourceControlRetries is set to true). | Int32 | No | 5 | 1.4 |
| modificationDelaySeconds | The minimum number of seconds allowed between the last check in and the start of a valid build. If any modifications are found within this interval the system will sleep long enough so the last checkin is just outside this interval. For example if the modification delay is set to 10 seconds and the last checkin was 7 seconds ago the system will sleep for 3 seconds and check again. This process will repeat until no modifications have been found within the modification delay window. This feature is in CruiseControl.NET for Source Control systems, like CVS, that do not support atomic checkins since starting a build half way through someone checking in their work could result in invalid 'logical' passes or failures. The property is optional though so if you are using a source control system with atomic checkins, leave it out (and it will default to '0'). |
Double | No | 0 | 1.0 |
| name | The name of your project - this must be unique for any given CruiseControl.NET server. | String | Yes | n/a | 1.0 |
| parameters | Dynamic build parameters - these are parameters that are set at build time instead of being hard-coded within the configuration file | Parameters array | No | None | 1.5 |
| prebuild | A set of Tasks to run before the build starts and before the source is updated. A failed task will fail the build and any subsequent tasks will not run. Tasks are run sequentially, in the order they appear in the configuration. | Task And Publisher Blocks array | No | None | 1.1 |
| publishers | The list of build-completed publishers used by this project. | Task And Publisher Blocks array | No | None | Xml Log Publisher |
| queue | The name of the integration queue that this project will use. By default, each project runs in its own queue. | String | No | Project name | 1.3 |
| queuePriority | The priority of this project within the integration queue. If multiple projects have pending requests in the specified queue then these requests will be executed according to their priority. Lower priority numbers indicate that integration requests for this project will execute before other projects in the same queue, however projects with priority 0 are always executed after projects with non-zero priorities in the same queue. | Int32 | No | 0 | 1.3 |
| remoteTargets | The remote machines that this project can build on. | String array | No | none | 1.6 |
| security | Any security for the project. | Project Level Security | No | Inherited Project Security | 1.5 |
| showForceBuildButton | (Should) show or hide the ForceBuildButton in UI programs. This is an extra setting on top of security. This is setting is mainly meant to disable the possibility to force a project via a UI. (dashboard and cctray) Forcing a build via other tools : ccmd, ... will work if you have the rights to do so. For example there is a project GatherErrorsDuringWeekend which is scheduled to run at Saturday and Sunday. Forcing this project on a weekday could mess up statistics or so. | Boolean | No | True | 1.6 |
| showStartStopButton | (Should) show or hide the Start - Stop Button in UI programs. This is an extra setting on top of security. This is setting is mainly meant to disable the possibility to start or stop a project via a UI. (dashboard and cctray) Starting - Stopping a build via other tools : ccmd, ... will work if you have the rights to do so. For example there is a project GatherErrorsDuringWeekend which is scheduled to run at Saturday and Sunday. Stopping this project on a weekday could mess up statistics or so. | Boolean | No | True | 1.6 |
| sourcecontrol | The source control block to use. | Source Control Blocks | No | Null_Source_Control | 1.0 |
| sourceControlErrorHandling | What action to take when a source control error occurs (during GetModifications). These are the possible values : * ReportEveryFailure : runs the publisher section whenever there is an error. * ReportOnRetryAmount : only runs the publisher section when maxSourceControlRetries has been reached, the publisher section will only be run once. * ReportOnEveryRetryAmount : runs the publisher section whenever the maxSourceControlRetries has been reached. When maxSourceControlRetries has been reached and the publisher section has ran, the counter is set back to 0. |
String - one of: * ReportEveryFailure * ReportOnRetryAmount * ReportOnEveryRetryAmount |
No | ReportEveryFailure | 1.4 |
| startupMode | The start-up mode for this project. | String - one of: * UseLastState * UseInitialState |
No | UseLastState | 1.5 |
| state | A state manager for the project. | State Manager Blocks | No | File State Manager | 1.0 |
| stopProjectOnReachingMaxSourceControlRetries | Stops the project on reaching maxSourceControlRetries or not. When set to true, the project will be stopped when the amount of consecutive source control errors is equal to maxSourceControlRetries. | Boolean | No | false | 1.4 |
| tasks | A set of Tasks to run as part of the build. A failed task will fail the build and any subsequent tasks will not run. Tasks are run sequentially, in the order they appear in the configuration. | Task And Publisher Blocks array | No | None | 1.0 |
| triggers | Trigger blocks allow you to specify when CruiseControl.NET will start a new integration cycle. Specifying an empty element (<triggers />) means integrations are only ever forced manually (for example using CCTray or the Web Dashboard.) Not including a <triggers> element at all means the project will behave like a <triggers /> element (before 1.4.3 the default when not including a <triggers> was a single Interval Trigger with default configuration). |
Trigger Blocks | No | None | 1.0 |
| webURL | A reporting URL for this project. This is used by CCTray and the Email Publisher. Typically you should navigate to the Project Report on the Dashboard, and use its URL. The default URL contains the machine name of the server. |
String | No | http://machineName/ccnet | 1.0 |
| writeSummaryFile | Write a small summary file that can be retrieved by clients, this contains very minimalistic info. | Boolean | No | false | 1.7 |
Notes¶
Setting the WebURL¶
The current format of the url for a project, as specified in the <webURL> element is:
1http://{dashboardserver}/{vdir}/server/{ccnetserver}/project/{projectname}/ViewLatestBuildReport.aspxFor example, if the dashboard was deployed on the server webserver to virtual directory ccnet, and if the project to monitor is called test on server cruise, the URL would be:
1http://webserver/ccnet/server/cruise/project/test/ViewLatestBuildReport.aspxAutomatically Generated¶
Documentation generated on Monday, 26 May 2014 at 7:18:00 AM