GoCD Configuration Reference

  1. <cruise>
  2. <server>
  3. <siteUrls>
  4. <siteUrl/>
  5. <secureSiteUrl/>
  6. </siteUrls>
  7. <security>
  8. <ldap>
  9. <bases>
  10. <base/>
  11. </bases>
  12. </ldap>
  13. <passwordFile/>
  14. <authConfigs>
  15. <authConfig>
  16. <property>
  17. <key/>
  18. <value/>
  19. </property>
  20. </authConfig>
  21. </authConfigs>
  22. <roles>
  23. <role>
  24. <policy>
  25. <allow/>
  26. <deny/>
  27. </policy>
  28. <users/>
  29. <user/>
  30. </role>
  31. <pluginRole/>
  32. <policy>
  33. <allow/>
  34. <deny/>
  35. </policy>
  36. <property>
  37. <key/>
  38. <value/>
  39. </property>
  40. </pluginRole>
  41. </roles>
  42. <admins>
  43. <role/>
  44. <user/>
  45. </admins>
  46. </security>
  47. <mailhost/>
  48. <backup/>
  49. <artifacts>
  50. <artifactsDir/>
  51. <purgeSettings>
  52. <purgeStartDiskSpace/>
  53. <purgeUptoDiskSpace/>
  54. </purgeSettings/>
  55. </artifacts>
  56. </server>
  57. <elastic>
  58. <agentProfiles>
  59. <agentProfile>
  60. <property>
  61. <key/>
  62. <value/>
  63. </property>
  64. </agentProfile>
  65. </agentProfiles>
  66. <clusterProfiles>
  67. <clusterProfile/>
  68. </clusterProfiles>
  69. </elastic>
  70. <repositories>
  71. <repository>
  72. <pluginConfiguration/>
  73. <configuration>
  74. <property>
  75. <key/>
  76. <value/>
  77. </property>
  78. </configuration>
  79. <packages>
  80. <package>
  81. <configuration>
  82. <property>
  83. <key/>
  84. <value/>
  85. </property>
  86. </configuration>
  87. </package>
  88. </packages>
  89. </repository>
  90. </repositories>
  91. <config-repos>
  92. <config-repo>
  93. <svn />
  94. <hg />
  95. <p4 />
  96. <git />
  97. <tfs />
  98. <scm />
  99. <configuration>
  100. <property>
  101. <key/>
  102. <value/>
  103. </property>
  104. </configuration>
  105. <rules>
  106. <allow>
  107. </allow>
  108. <deny>
  109. </deny>
  110. </rules>
  111. </config-repo>
  112. </config-repos>
  113. <artifactStores>
  114. <artifactStore>
  115. <property>
  116. <key/>
  117. <value/>
  118. </property>
  119. </artifactStore>
  120. </artifactStores>
  121. <secretConfigs>
  122. <secretConfig>
  123. <description>
  124. </description>
  125. <configuration>
  126. <property>
  127. <key/>
  128. <value/>
  129. </property>
  130. </configuration>
  131. <rules>
  132. <allow>
  133. </allow>
  134. <deny>
  135. </deny>
  136. </rules>
  137. </secretConfig>
  138. </secretConfigs>
  139. <pipelines>
  140. <authorization>
  141. <admins>
  142. <user/>
  143. <role/>
  144. </admins>
  145. <view>
  146. <user/>
  147. <role/>
  148. </view>
  149. <operate>
  150. <user/>
  151. <role/>
  152. </operate>
  153. </authorization>
  154. <pipeline>
  155. <params>
  156. <param/>
  157. </params>
  158. <trackingtool/>
  159. <timer/>
  160. <environmentvariables>
  161. <variable>
  162. <value/>
  163. </variable>
  164. </environmentvariables>
  165. <materials>
  166. <svn>
  167. <filter>
  168. <ignore/>
  169. </filter>
  170. </svn>
  171. <hg>
  172. <filter>
  173. <ignore/>
  174. </filter>
  175. </hg>
  176. <p4>
  177. <view/>
  178. <filter>
  179. <ignore/>
  180. </filter>
  181. </p4>
  182. <git>
  183. <filter>
  184. <ignore/>
  185. </filter>
  186. </git>
  187. <tfs>
  188. <filter>
  189. <ignore/>
  190. </filter>
  191. </tfs>
  192. <package/>
  193. <pipeline/>
  194. </materials>
  195. <stage>
  196. <approval>
  197. <authorization>
  198. <role/>
  199. <user/>
  200. </authorization>
  201. </approval>
  202. <environmentvariables>
  203. <variable>
  204. <value/>
  205. </variable>
  206. </environmentvariables>
  207. <jobs>
  208. <job>
  209. <environmentvariables>
  210. <variable>
  211. <value/>
  212. </variable>
  213. </environmentvariables>
  214. <resources>
  215. <resource/>
  216. </resources>
  217. <tasks>
  218. <fetchartifact>
  219. <runif/>
  220. <oncancel/>
  221. </fetchartifact>
  222. <ant>
  223. <runif/>
  224. <oncancel/>
  225. </ant>
  226. <nant>
  227. <runif/>
  228. <oncancel/>
  229. </nant>
  230. <rake>
  231. <runif/>
  232. <oncancel/>
  233. </rake>
  234. <exec>
  235. <arg/>
  236. <runif/>
  237. <oncancel/>
  238. </exec>
  239. </tasks>
  240. <artifacts>
  241. <artifact/>
  242. </artifacts>
  243. <tabs>
  244. <tab/>
  245. </tabs>
  246. </job>
  247. </jobs>
  248. </stage>
  249. </pipeline>
  250. </pipelines>
  251. <templates>
  252. <pipeline>
  253. <stage>
  254. </stage>
  255. </pipeline>
  256. </templates>
  257. <environments>
  258. <environment>
  259. <environmentvariables>
  260. <variable>
  261. <value/>
  262. </variable>
  263. </environmentvariables>
  264. <pipelines>
  265. <pipeline/>
  266. </pipelines>
  267. </environment>
  268. </environments>
  269. </cruise>

top

Configuration reference

The <cruise> element is the root element of the configuration.

top

The <server> element can be used to define information and attributes of the Go Server.

Attributes

AttributeRequiredDescription
jobTimeoutNoThis entry will be used as the default timeout value for hung jobs. A job is considered as hung if it does not generate any console output for “jobTimeout” minutes. If the attribute is not specified job will never timeout.
commandRepositoryLocationYes (auto-generated)Specifies the location of the command repository relative to go-server_install_root/db/command_repository. The bundled repository is in a directory named default.
serverIdYes (auto-generated)This value uniquely identifies a Go server installation. It may be used by features that require unique names/identifiers across different Go server installations. This attribute need not be specified for a new server. In case no value is given, server auto-generates a random UUID an assigns it as serverId. This value should never be changed for an existing server. Administrator should clear this attribute before copying configuration to a different installation.
agentAutoRegisterKeyNoThe key specified here is used by agents for auto-registration.

Examples

  1. <cruise>
  2. <server jobTimeout='30'>
  3. </server>
  4. </cruise>

top

The <siteUrls> element is used to define <siteUrl> and <secureSiteUrl>.

Notes

  • If both <siteUrl> and <secureSiteUrl> are not defined, GoCD URLs will use the default domain which in most cases will be http://your-go-server:8153
  • If only <siteUrl> is defined and is not HTTPS, GoCD URLs will be composed from the <siteUrl> entry. In this case, the secure pages of GoCD will not be navigable.
  • If only <siteUrl> is defined and is HTTPS, GoCD URLs will be composed from the <siteUrl> entry and all pages will be HTTPS.
  • If only <secureSiteUrl> is defined, GoCD URLs will use the default domain for non-HTTPS pages, while HTTPs pages will be composed from the <secureSiteUrl> entry.

Examples

  1. <siteUrls>
  2. <siteUrl>http://siteUrl.com</siteUrl>
  3. <secureSiteUrl>https://secureSiteUrl.com</secureSiteUrl>
  4. </siteUrls>

top

The <siteUrl> element is used by GoCD Server to generate links for emails, feeds etc., where we cannot have relative URLs. For example, if you have fronted GoCD with a reverse proxy, this value should be the base URL for the proxy and not the internal GoCD address. For this reason, it is necessary to specify this configuration. Format: [protocol]://[host]:[port]. You need to define the [port] in case GoCD uses a non-standard port. The [Protocol] can be HTTP or HTTPs.

Examples

  1. <siteUrls>
  2. <siteUrl>http://siteUrl.com</siteUrl>
  3. ...
  4. </siteUrls>

top

The <secureSiteUrl> element is used to specify value of the base HTTPS URL.Certain features in GoCD require an HTTPS(SSL) endpoint. If you wish that your primary site URL be HTTP, but still want to have HTTPS endpoints for the features that require SSL,you can use this element. Format: https://[host]:[port]. You need to define the [port] in case GoCD uses a non-standard port.

Examples

  1. <siteUrls>
  2. ...
  3. <secureSiteUrl>https://secureSiteUrl.com</secureSiteUrl>
  4. </siteUrls>

top

The <security> element can be used to enable authentication. If the element is not defined anyone can use Go without logging in. We currently support enabling authentication using Authorization plugin endpoint. Support for LDAP and simple password-file authentication is available out of box via the bundled plugins for the same. You can use more than one authentication mechanism if you want. Support for inbuilt LDAP and password file tags in configuration has been deprecated.

Examples

  1. <server artifactsdir="/var/lib/go/big-artifacts-folder">
  2. <security>
  3. <authConfigs>
  4. <authConfig id="profile-id" pluginId="cd.go.authentication.ldap">
  5. <property>
  6. <key>Url</key>
  7. <value>ldap://xxx.yourcompany.com</value>
  8. </property>
  9. <property>
  10. <key>ManagerDN</key>
  11. <value>cn=Acitivity Directory LDap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxx,dc=yyyy,dc=com</value>
  12. </property>
  13. <property>
  14. <key>Password</key>
  15. <value>secret</value>
  16. </property>
  17. <property>
  18. <key>SearchBases</key>
  19. <value>ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com</value>
  20. </property>
  21. <property>
  22. <key>UserLoginFilter</key>
  23. <value>(sAMAccountName={0})</value>
  24. </property>
  25. <property>
  26. <key>UserSearchFilter</key>
  27. <value>(sAMAccountName={0})</value>
  28. </property>
  29. <property>
  30. <key>DisplayNameAttribute</key>
  31. <value>displayName</value>
  32. </property>
  33. <property>
  34. <key>EmailAttribute</key>
  35. <value>mail</value>
  36. </property>
  37. </authConfig>
  38. </authConfigs>
  39. </security>
  40. </server>

top

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

AttributeRequiredDescription
hostnameYesThe SMTP mail server which Go will use to send email. For example, hostname=”mailhost.yourcompany.com”
portYesThe mail port to use. Typically this will be the default mail port of 25.
usernameYesThe username which Go should use to login to the mail host.
passwordYesThe password to access the mailhost.
tlsNoUse TLS(Transport Layer Security) or not. The default value is ‘false’. Use ‘true’ to enable TLS security.
fromYesGo 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=”go-admin@yourcompany.com”.
adminYesGo admintrator’s email address. Go will send diagnostic messages to this email address. For example, Go will send a warning message if it is running out of disk space.

Examples

  1. <mailhost hostname="mailhost.yourcompany.com" port="25" username="go-user" password="crs123" tls="false" from="go@yourcompany.com" admin="goadministrator@yourcompany.com" />

top

The <backup> element is used to configure backups.

AttributeRequiredDescription
scheduleNoThe cron-like specification to perform a backup.
postBackupScriptNoA script that will be invoked on the GoCD server after backup is performed (successfully, or otherwise). See cron backups for details about this script.
emailOnSuccessNoBoolean indicating whether email should be sent on a successful backup. Requires that mailhost config be setup.
emailOnFailureNoBoolean indicating whether email should be sent on a failed backup backup. Requires that mailhost config be setup.

Examples

For example: to perform a backup once a night at 10pm on weekdays and call the /usr/local/bin/upload-to-s3 script after the backup is done.

  1. <server>
  2. <backup schedule="0 0 22 ? * MON-FRI" postBackupScript="/usr/local/bin/upload-to-s3" emailOnSuccess="false" emailOnFailure="true"/>
  3. ...
  4. </server>

Go uses the Quartz scheduler internally. For convenience we reproduce the Quartz cron documentation here:

Format

A cron expression is a string comprised of 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields are as follows:

Field NameMandatory?Allowed ValuesAllowed Special Characters
SecondsYES0-59, - /
MinutesYES0-59, - /
HoursYES0-23, - /
Day of monthYES1-31, - ? / L W\
MonthYES1-12 or JAN-DEC, - /
Day of weekYES1-7 or SUN-SAT, - ? / L #
YearNOempty, 1970-2099, - * /

So cron expressions can be as simple as this: * * * * * ? or more complex, like this: 0 15 10 ? * 6L 2002-2005

Special characters

  • * (“all values”) - used to select all values within a field. For example, “*” in the minute field means “every minute”.

  • ? (“no specific value”) - useful when you need to specify something in one of the two fields in which the character is allowed, but not the other. For example, if I want my trigger to fire on a particular day of the month (say, the 10th), but don’t care what day of the week that happens to be, I would put “10” in the day-of-month field, and “?” in the day-of-week field. See the examples below for clarification.

  • - - used to specify ranges. For example, “10-12” in the hour field means “the hours 10, 11 and 12”.

  • , - used to specify additional values. For example, “MON,WED,FRI” in the day-of-week field means “the days Monday, Wednesday, and Friday”.

  • / - used to specify increments. For example, “0/15” in the seconds field means “the seconds 0, 15, 30, and 45”. And “5/15” in the seconds field means “the seconds 5, 20, 35, and 50”. You can also specify ‘/’ after the ‘’ character - in this case ‘’ is equivalent to having ‘0’ before the ‘/’. ‘1/3’ in the day-of-month field means “fire every 3 days starting on the first day of the month”.

  • L (“last”) - has different meaning in each of the two fields in which it is allowed. For example, the value “L” in the day-of-month field means “the last day of the month” - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means “7” or “SAT”. But if used in the day-of-week field after another value, it means “the last xxx day of the month” - for example “6L” means “the last friday of the month”. When using the ‘L’ option, it is important not to specify lists, or ranges of values, as you’ll get confusing results.

  • W (“weekday”) - used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify “15W” as the value for the day-of-month field, the meaning is: “the nearest weekday to the 15th of the month”. So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify “1W” as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not ‘jump’ over the boundary of a month’s days. The ‘W’ character can only be specified when the day-of-month is a single day, not a range or list of days. The ‘L’ and ‘W’ characters can also be combined in the day-of-month field to yield ‘LW’, which translates to “last weekday of the month”.

  • # - used to specify “the nth” XXX day of the month. For example, the value of “6#3” in the day-of-week field means “the third Friday of the month” (day 6 = Friday and “#3” = the 3rd one in the month). Other examples: “2#1” = the first Monday of the month and “4#5” = the fifth Wednesday of the month. Note that if you specify “#5” and there is not 5 of the given day-of-week in the month, then no firing will occur that month. The legal characters and the names of months and days of the week are not case sensitive. MON is the same as mon.

Examples

Here are some full examples:

ExpressionMeaning
0 0 12 ?Fire at 12pm (noon) every day
0 15 10 ? Fire at 10:15am every day
0 15 10 ?Fire at 10:15am every day
0 15 10 ? Fire at 10:15am every day
0 15 10 ? 2005Fire at 10:15am every day during the year 2005
0 14 ?Fire every minute starting at 2pm and ending at 2:59pm, every day
0 0/5 14 ?Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
0 0/5 14,18 ?Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
0 0-5 14 ?Fire every minute starting at 2pm and ending at 2:05pm, every day
0 10,44 14 ? 3 WEDFire at 2:10pm and at 2:44pm every Wednesday in the month of March.
0 15 10 ? MON-FRIFire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
0 15 10 15 ?Fire at 10:15am on the 15th day of every month
0 15 10 L ?Fire at 10:15am on the last day of every month
0 15 10 ? 6LFire at 10:15am on the last Friday of every month
0 15 10 ? 6LFire at 10:15am on the last Friday of every month
0 15 10 ? 6L 2002-2005Fire at 10:15am on every last friday of every month during the years 2002, 2003, 2004 and 2005
0 15 10 ? 6#3Fire at 10:15am on the third Friday of every month
0 0 12 1/5 ?Fire at 12pm (noon) every 5 days every month, starting on the first day of the month.
0 11 11 11 11 ?Fire every November 11th at 11:11am.

Pay attention to the effects of ‘?’ and ‘*’ in the day-of-week and day-of-month fields!

Notes

  • Support for specifying both a day-of-week and a day-of-month value is not complete (you must currently use the ‘?’ character in one of these fields).
  • Be careful when setting fire times between mid-night and 1:00 AM - “daylight savings” can cause a skip or a repeat depending on whether the time moves back or jumps forward.

top

The <artifacts> element can be used to define information related to artifacts.In this, artifact directory can be defined using <artifactsDir> and purge settings can be using <purgeSettings>

Examples

  1. <artifacts>
  2. <artifactsDir>artifacts</artifactsDir>
  3. <purgeSettings>
  4. <purgeStartDiskSpace>30.0</purgeStartDiskSpace>
  5. <purgeUptoDiskSpace>60.0</purgeUptoDiskSpace>
  6. </purgeSettings>
  7. </artifacts>

top

The <artifactsDir> element is used to define the directory where GoCD will store its information, including artifacts published by jobs.The default value is ‘artifacts’ in the folder where the GoCD 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 GoCD has permission to access that directory. Also you should be aware of that changing this value while Go Server is running won’t take effect until GoCD Server is restarted.

Examples

  1. <artifacts>
  2. <artifactsDir>artifacts</artifactsDir>
  3. ...
  4. </artifacts>

top

The <purgeSettings> element is used to configure GoCD to automatically delete old artifacts when the available disk space on the server is low.

The <purgeSettings> can be configured with <purgeStartDiskSpace> and <purgeUptoDiskSpace>. If available disk space on the server is lower than <purgeStartDiskSpace> GB, GoCD will purge old artifacts till the available disk space is greater than <purgeUptoDiskSpace>GB.

Notes

  • Artifacts will never be deleted if purgeStartDiskSpace and purgeUptoDiskSpace are not defined.

  • If purgeStartDiskSpace is defined,purgeUptoDiskSpaceshould be defined.

Examples

  1. <purgeSettings>
  2. <purgeStartDiskSpace>30.0</purgeStartDiskSpace>
  3. <purgeUptoDiskSpace>60.0</purgeUptoDiskSpace>
  4. </purgeSettings>

top

The <purgeStartDiskSpace> element is used to define the limit of available disk space. If actual available disk space is less than the limit, GoCD will start purging the artifacts.

Notes

  • It should be smaller than <purgeUptoDiskSpace>.

Examples

  1. <purgeSettings>
  2. <purgeStartDiskSpace>30.0</purgeStartDiskSpace>
  3. ...
  4. </purgeSettings>

top

The <purgeUptoDiskSpace> element is used to define the limit of available disk space. GoCD will stop purging artifacts, when the available disk space reaches the specified limit.

Notes

  • It should be greater than <purgeStartDiskSpace>.

Examples

  1. <purgeSettings>
  2. ...
  3. <purgeUptoDiskSpace>30.0</purgeUptoDiskSpace>
  4. </purgeSettings>

top

[Deprecated]

The <ldap> element is used to specify the ldap server. Users can access with their username and password from this ldap server.

Attributes

AttributeRequiredDescription
uriYesuri for the ldap server. For example, uri=”ldap://ldap.yourcompany.com”
managerDnYesFor example, managerDn=”cn=Active Directory Ldap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxxx,dc=yyyy,dc=com”
managerPasswordYesGo will connect to the LDAP server with this password
searchFilterNoe.g. searchFilter=”(sAMAccountName={0})”

Examples

  1. <security>
  2. <ldap uri="ldap://xxx.yourcompany.com"
  3. managerDn="cn=Acitivity Directory LDap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
  4. managerPassword="password"
  5. searchFilter="(sAMAccountName={0})" />
  6. <bases>
  7. <base value="ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com"/>
  8. </bases>
  9. <passwordFile path="/home/go/admins.properties"/>
  10. <roles>
  11. <role name="go-admin">
  12. <user>Jez</user>
  13. <user>lqiao</user>
  14. </role>
  15. </roles>
  16. <admins>
  17. <role>go-admin</role>
  18. <user>lqiao</user>
  19. </admins>
  20. </security>

top

The <bases> element is used to specify a list of search bases (the distinguished name of the search base object) which defines the location in the directory from which the LDAP search begins.

top

The <base> element is used to specify a search base (the distinguished name of the search base object) defines the location in the directory from which the LDAP search begins.

AttributeRequiredDescription
valueYesThe search base.
  1. <ldap uri="ldap://xxx.yourcompany.com"
  2. managerDn="cn=Acitivity Directory LDap User,ou=InformationSystems,ou=SharedAccounts,ou=Principal,dc=xxxx,dc=yyyy,dc=com"
  3. managerPassword="password"
  4. searchFilter="(sAMAccountName={0})" />
  5. <bases>
  6. <base value="ou=Employees,ou=Enterprise,ou=Principal,dc=xxxx,dc=yyyy,dc=com"/>
  7. </bases>
  8. </ldap>

top

[Deprecated]

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.

AttributeRequiredDescription
pathYesThe absolute path of the password file.

Examples

Suppose the password file is admins.properties, which is located in /home/go. 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:

  1. <security>
  2. <passwordFile path="/home/go/admins.properties"/>
  3. </security>

The username and password could be set in admins.properties as follows:

  1. Jez=ThmbShxAtJepX80c2JY1FzOEmUk
  2. lqiao=TfkgShslgJepX80c2JY1trwEskT

top

Using <authConfigs> element GoCD administrators can provide one or more authorization configurations to connect with the authorization server(s).

Example

  1. <authConfigs>
  2. <authConfig id="file-auth-config" pluginId="cd.go.authentication.passwordfile">
  3. ...
  4. </authConfig>
  5. <authConfig id="ldap" pluginId="cd.go.authentication.ldap">
  6. ...
  7. </authConfig>
  8. </authConfigs>

top

The <authConfig> specifies the configuration to be used by the authorization plugin. This will usually allow administrators to configure the connection settings for your authorization plugin, and may include configuration like URLs and credentials, among others.

An authConfig should have a unique id attribute and should be associated to plugin through the pluginId attribute.

Attributes

AttributeRequiredDescription
idYesUnique Id of authConfig.
pluginIdYesThe Id of authorization plugin.
allowOnlyKnownUsersToLoginNoAllow only those users to login who have been explicitly added by an admin. If false, any new user who tries to login and is present in your password file or LDAP will be automatically created as a Go user. (Default=false)

Refer to your plugin’s documentation to know the property keys to be configured.

Example:

  1. <authConfig id="file-auth-config" pluginId="cd.go.authentication.passwordfile" allowOnlyKnownUsersToLogin="false">
  2. <property>
  3. <key>PasswordFilePath</key>
  4. <value>/etc/go/password.properties</value>
  5. </property>
  6. </authConfig>

top

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

Examples

  1. <security>
  2. ...
  3. <roles>
  4. <role name="go-admin">
  5. <user>Jez</user>
  6. <user>lqiao</user>
  7. </role>
  8. </roles>
  9. </security>

top

The <role> element is used to define a group of users who perform similar tasks. Optionally, the <role> element can specify a policy which defines the permission model for the users defined as part of the current role. In a <role> element, Users are added by adding the sub-tag <users> and Policy is added by adding the sub-tag <policy>.

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 Go. 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.
AttributeRequiredDescription
nameYesThe name of the role.

Examples

Two users would be in the role ‘environment-operators’, they are Jez and lqiao have access to administer all the environments expect environments matching prod_* name.

  1. <roles>
  2. <role name="environment-operators">
  3. <policy>
  4. <deny action="administer" type="environment">prod_*</deny>
  5. <allow action="administer" type="environment">*</allow>
  6. </policy>
  7. <users>
  8. <user>Jez</user>
  9. <user>lqiao</user>
  10. </users>
  11. </role>
  12. </roles>

top

List of users in a role.

top

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

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

Notes:

Examples

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

  1. <role name="pipeline-operators">
  2. <users>
  3. <user>Jez</user>
  4. <user>lqiao</user>
  5. </users>
  6. </role>

The <policy> element defines the permissions for the users belonging to the users of a role.

In a <policy> element, the allow permission can added by adding the sub-tag <allow> and deny permission can be added by adding the sub-tag <deny>.

Examples

The following policy would grant users the permissions to administer to all environments expect environments matching prod_* name.

  1. <policy>
  2. <deny action="administer" type="environment">prod_*</deny>
  3. <allow action="administer" type="environment">*</allow>
  4. </policy>

The <allow> element under policy grants permissions to the defined GoCD entity based on the type, action and resource.

The value of the allow element defines the resource on which policy should be applied.

Notes:

AttributeRequiredDescription
typeYesThe type of the GoCD entity to grant permissions on. The supported values for type are environment and config_repo.
actionYesThe operation that can be performed on the GoCD entity. The supported values for action are administer and view.

Examples

The following policy would grant users the permissions to administer to all environments matching prod_* name.

  1. <allow action="administer" type="environment">prod_*</allow>

An administrator can use * to provide allow access of all type and action.

Examples

  1. <allow action="*" type="*">*</allow>

The <deny> element under policy deny the access to the defined GoCD entity based on the type, action and resource.

The value of the deny element defines the resource on which policy should be applied.

Notes:

AttributeRequiredDescription
typeYesThe type of the GoCD entity to deny the access on. The supported values for type are environment and config_repo.
actionYesThe operation that can not be performed on the GoCD entity. The supported values for action are administer and view.

Examples

The following policy would deny the administer access to all environments matching prod_* name.

  1. <deny action="administer" type="environment">prod_*</deny>

An administrator can use * to deny all the access of all type and action.

Examples

  1. <deny action="*" type="*">*</deny>

top

The <pluginRole> element is used to define roles in GoCD. Unlike role which contains a list of users, pluginRole provides configuration to map a GoCD role to a role defined in an external authorization server managed by an Authorization plugin. e.g pluginRole can be used to define mappings between LDAP group and GoCD roles.

Optionally, the <pluginRole> element can specify a policy which defines the permission model for the users of the current role.

Notes:

AttributeRequiredDescription
nameYesThe name of the role.
authConfigIdYesId of an authorization config.

Refer to your plugin’s documentation to know the property keys to be configured for the pluginRole.

Examples

  1. <roles>
  2. <pluginRole name="SuperAdmin" authConfigId="auth_config_id">
  3. <policy>
  4. <deny action="administer" type="environment">prod_*</deny>
  5. <allow action="administer" type="environment">*</allow>
  6. </policy>
  7. <property>
  8. <key>MemberOfAttribute</key>
  9. <value>memberOf</value>
  10. </property>
  11. <property>
  12. <key>MatchingGroups</key>
  13. <value>CN=Dev,OU=Groups,DC=some,DC=enterprise,DC=com</value>
  14. </property>
  15. </pluginRole>
  16. </roles>

top

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

Notes:

The user must be in your LDAP or passwordFile.

Examples

  1. <security>
  2. ...
  3. <admins>
  4. <role>go-admin</role>
  5. <user>lqiao</user>
  6. </admins>
  7. </security>

top

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

Notes:

Examples

The users in role ‘go-admin’ would be administrators.

  1. <admins>
  2. <role>go-admin</role>
  3. <user>lqiao</user>
  4. </admins>

top

Notes:

Examples

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

  1. <admins>
  2. <user>Jez</user>
  3. <user>lqiao</user>
  4. </admins>

top

Notes:

  • The role must be defined in <roles>.

Examples

  1. <view>
  2. <user>lqiao<user>
  3. <role>_readonly_member<role>
  4. </view>

The <elastic> element is used to provide configurations for the elastic agents.

AttributeRequiredDescription
jobStarvationTimeoutNoTimeout in minutes. If a job that requires an elastic agent is not assigned within the specified period, the elastic agent plugin will be notified to create a new elastic agent.

Examples

  1. <elastic jobStarvationTimeout="10">
  2. <agentProfiles>
  3. <agentProfile id="aws.small" pluginId="aws">
  4. ...
  5. </agentProfile>
  6. </agentProfiles>
  7. </elastic>

top

<agentProfiles> element specifies the profiles to configure elastic agents.

There can be zero or more profiles.

Examples

  1. <agentProfiles>
  2. <agentProfile id="aws.small" pluginId="aws" clusterProfileId="cluster-profile-id" >
  3. ...
  4. </agentProfile>
  5. </agentProfiles>

top

<agentProfile> specifies the configuration to be used to create an elastic-agent instance. A profile should have a unique id attribute, should be associated with a cluster via clusterProfileId attribute and with plugin through the pluginId attribute.

Attributes

AttributeRequiredDescription
idYesUnique Id of profile.
pluginIdYesThe Id of elastic-agent plugin.
clusterProfileIdYesThe Id of cluster profile.

Example:

  1. <agentProfile id="ec2.small-us-east" pluginId="com.example.ec2" clusterProfileId="cluster-profile-id">
  2. <property>
  3. <key>ami-id</key>
  4. <value>ami-6ac7408f</value>
  5. </property>
  6. <property>
  7. <key>region</key>
  8. <value>us-east-1</value>
  9. </property>
  10. </agentProfile>

top

<clusterProfiles> element specifies the profiles to configure clusters.

There can be zero or more cluster profile.

Examples

  1. <clusterProfiles>
  2. <clusterProfile id="cluster.small" pluginId="aws">
  3. ...
  4. </clusterProfile>
  5. </clusterProfiles>

top

<clusterProfile> specifies the configuration to be used to to create/manage a cluster. A cluster profile should have a unique id attribute and should be associated to plugin through the pluginId attribute.

Attributes

AttributeRequiredDescription
idYesUnique Id of cluster profile.
pluginIdYesThe Id of elastic-agent plugin.

Example:

  1. <clusterProfile id="cluster-us-east" pluginId="com.example.ec2">
  2. <property>
  3. <key>GoServerUrl</key>
  4. <value>https://your-server-host:8154/go</value>
  5. </property>
  6. <property>
  7. <key>ClusterName</key>
  8. <value>Cluster</value>
  9. </property>
  10. </profile>

top

The <config-repos> element is a container of many <config-repo>.

Example

  1. <cruise>
  2. ...
  3. <config-repos>
  4. <config-repo pluginId="json.config.plugin" id="gocd-json-config-example">
  5. <git url="https://github.com/tomzo/gocd-json-config-example.git" />
  6. </config-repo>
  7. <config-repo pluginId="yaml.config.plugin" id="gocd-yaml-config-example">
  8. <git url="https://github.com/tomzo/gocd-yaml-config-example.git" />
  9. <configuration>
  10. <property>
  11. <key>file_pattern</key>
  12. <value>**/*.gocd.yaml</value>
  13. </property>
  14. </configuration>
  15. </config-repo>
  16. </config-repos>
  17. </cruise>

top

The <config-repo> element specifies a single configuration repository. It must contain exactly one SCM material and may contain additional configuration section.

Attributes

AttributeRequiredDescription
pluginIdYesThe ID of configuration repository plugin. E.g. json.config.plugin.
idYesThe ID of the configuration repository. ID must be a unique alphanumeric string. It can also contain -,_,..

Example

  1. <cruise>
  2. ...
  3. <config-repos>
  4. <config-repo pluginId="yaml.config.plugin" id="gocd-yaml-config-example">
  5. <git url="https://github.com/tomzo/gocd-yaml-config-example.git" />
  6. <configuration>
  7. <property>
  8. <key>file_pattern</key>
  9. <value>**/*.gocd.yaml</value>
  10. </property>
  11. </configuration>
  12. </config-repo>
  13. </config-repos>
  14. </cruise>

{#config-repo-configuration}

The <configuration> element is optional part of config repo definition. Keys and values are specified and handled by particular plugin. This section can be used to customize how config repo plugin works when parsing this specific repository.

Example

  1. <configuration>
  2. <property>
  3. <key>file_pattern</key>
  4. <value>*.go.yaml</value>
  5. </property>
  6. <property>
  7. <key>allowed_pipelines_regex</key>
  8. <value>project-X-.*</value>
  9. </property>
  10. </configuration>

top

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

Attributes

AttributeRequiredDescription
urlYesURL for the remote repository. Go supports the following protocols for subversion: http, https, svn and svn+ssh, but does not support ‘file:///’.
usernameNoThe user account for the remote repository.
passwordNoThe password for the specified user
encryptedPasswordNoThe encrypted password for the specified user
checkexternalsNoThe 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 be included as part of configuration.
materialNameNoThe 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. The max length is 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. For config repo materials, autoUpdate is always set to true.

Notes:

Go cannot automatically accept svn SSL certificates. If you are using https for svn repository, you have to go to the Server, and as the user ‘go’ do a command “svn update” to store the certificates in the cache permanently.

Examples:

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <svn url="http://svn-server.com/framework" />
  3. </config-repo>

top

The config repo <hg> material element specifies the location of your code base in a Mercurial repository. Go supports the following protocols for Mercurial: http, ssh.

Notes:

You must install Mercurial 1.5 or above on the Go Server. Go does not ship with Mercurial.

Attributes

AttributeRequiredDescription
urlYesURL to fetch source code from the Mercurial repository. If you specify the username and password for the Mercurial repository, you should put them into the url. Mercurial supports an optional identifier after # in the url, which indicates a particular branch, tag or changeset. This option can be used to configure mercurial branches in Go.
materialNameNoThe 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. The max length is 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. For config repo materials, autoUpdate is always set to true.

Examples

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <hg url="http://username:password@your-hg/"/>
  3. </config-repo>

Specifying a mercurial branch.

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <hg url="http://username:password@your-hg#branch_name"/>
  3. </config-repo>

Note: Do not use configrepo material type for config-repo pipeline material configuration when using mercurial branch as it will result in merge error.

top

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

Attributes

AttributeRequiredDescription
portYesPerforce 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.
usernameNoPerforce username to use.
passwordNoPassword for the specified user.
encryptedPasswordNoEncrypted Password for the specified user.
useTicketsNoSet to true to work with perforce tickets. Go 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.
viewYesValid Perforce view. The view should be a sub-element of P4. Click here to see details about VIEW of Perforce.
materialNameNoThe 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. The max length is 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. For config repo materials, autoUpdate is always set to true.

Notes:

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

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

Go creates a p4 client to check out files into its sandbox with the ‘clobber’ option set. All other options use default values as defined by Perforce. Client name is generated automatically by Go. Hence, you can use anything as ‘clientname’ on the right-hand side in view mapping. The client name format is: cruise-[hostname]-[config repo id]-[a random hash code], for example “cruise-myhostname-configrepo1-wOaJ9kjpfgOLQCncki19ikXt5Q”.

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

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <p4 port="10.18.3.102:1666" username="userName" password="passwd">
  3. <view><![CDATA[
  4. //depot/dev/src... //anything/src/...
  5. //depot/dev/test... //anything/test/...
  6. //depot/dev/main/docs/... //anything/docs/...
  7. ]]></view>
  8. </p4>
  9. </config-repo>

top

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

Notes:

git versions 1.9 and above are supported by Go.

If ‘branch’ is defined, Go will check out the specified branch. Otherwise, Go will check out the master branch.

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

While installing msysGit On Windows machines for Go server, please choose Option iii, namely Run Git and included UNIX tools from windows command prompt

If you are using git through SSH on windows, please ensure that the HOME user environment variable is set to the full path of the parent directory where the .ssh/ directory is located.

Attributes

AttributeRequiredDescription
urlYesgit url for the repository.
branchNoa branch name in the repository.
materialNameNoThe 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. The max length is 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. For config repo materials, autoUpdate is always set to true.

Examples are:

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <git url="git://127.0.0.1/precommit.git" branch="1.3branch"/>
  3. </config-repo>

top

The config repo <tfs> material element specifies the location of your code base in a TFS Source repository.

Attributes

AttributeRequiredDescription
urlYesurl for the Collection on the TFS Server.
DomainNoDomain name for TFS authentication credentials.
UsernameYesUsername of the account to access the TFS collection.
PasswordYesPassword of the account to access the TFS collection.
encryptedPasswordNoEncrypted Password of the account to access the TFS collection.
Project PathYesThe project path within the TFS collection.
materialNameNoThe 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. The max length is 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. For config repo materials, autoUpdate is always set to true.

Examples are:

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <tfs url="http://10.21.3.210:8080/tfs/New" domain="DOMAIN" username="jim" password="as802nsk9==" projectPath="$/webapp" />
  3. </config-repo>

top

The config repo <scm> material element specifies the location of your code base in any of the SCM repositories.

Attributes

AttributeRequiredDescription
refYesThe unique package repository id.

Examples are:

  1. <config-repo pluginId="json.config.plugin" id="repo1">
  2. <scm ref="e289f497-057b-46bc-bb69-8043454f5c1b"/>
  3. </config-repo>

top

The config repo <rules> rules element is a container for allow and deny rule. More about rules can be read from here.

Examples are:

  1. <rules>
  2. <allow action="refer" type="environment">dev</allow>
  3. <deny action="refer" type="environment">prod</allow>
  4. </rules>

top

The <allow> element is the rule which allows referring the specified configured type and resource.

Attributes

AttributeRequiredDescription
actionYesAction for the entity specified under attribute type. Supported values are refer.
typeYesThe GoCD entity type for which rule will be applied. Supported values are *, environment, pipeline_group, pipeline.

Example:

  1. <allow action="refer" type="*">*</allow>

top

The <deny> element is the rule which denies the referral of the defined type and resource.

Attributes

AttributeRequiredDescription
actionYesAction for the entity specified under attribute type. Supported values are refer.
typeYesThe GoCD entity type for which rule will be applied. Supported values are *, environment, pipeline_group, pipeline.

Example:

  1. <deny action="refer" type="*">*</deny>

top

The <repositories> element is a container of package repositories.

Example

  1. <cruise>
  2. ...
  3. <repositories>
  4. <repository id="repo-id" name="repo-name">
  5. <pluginConfiguration id="plugin-id" version="plugin-version" />
  6. <configuration>
  7. <property>
  8. <key>property-name</key>
  9. <value>property-value</value>
  10. </property>
  11. ...
  12. </configuration>
  13. <packages>
  14. <package id="package-id" name="package-name" >
  15. <configuration>
  16. <property>
  17. <key>property-name</key>
  18. <value>property-value</value>
  19. </property>
  20. ...
  21. </configuration>
  22. </package>
  23. </packages>
  24. </repository>
  25. </repositories>
  26. </cruise>

top

The <repository> element specifies a single repository. Repository must be be unique by id and name (name is case-insensitive) across repositories configuration.

Attributes

AttributeRequiredDescription
idNoThe id uniquely identifies a package repository by GO. This attribute need not be specified. In case no value is given, server auto-generates a random UUID and assigns it as repository id.
nameYesThe name uniquely identifies a package repository which will be specified by user and same will be used to display on screen. Repository 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 Go and the length should be less than 255 characters.

Example

  1. <cruise>
  2. ...
  3. <repositories>
  4. <repository id="repo-id" name="repo-name">
  5. <pluginConfiguration id="plugin-id" version="plugin-version" />
  6. <configuration>
  7. <property>
  8. <key>property-name</key>
  9. <value>property-value</value>
  10. </property>
  11. ...
  12. </configuration>
  13. <packages>
  14. <package id="package-id" name="package-name" >
  15. <configuration>
  16. <property>
  17. <key>property-name</key>
  18. <value>property-value</value>
  19. </property>
  20. ...
  21. </configuration>
  22. </package>
  23. </packages>
  24. </repository>
  25. </repositories>
  26. </cruise>

top

The <pluginConfiguration> element specifies configuration related to plugin.

Attributes

AttributeRequiredDescription
idYesSpecifies plugin id which is going to handle repository configuration
versionYesSpecifies plugin version which is going to handle repository configuration

top

The <configuration> element specifies configuration related repository or package as one or more properties.

top

The <property> element holds key and value.

top

The <key> element specifies name of property.

top

The <value> element specifies value of property.

top

The <packages> element specifies list of packages under a repository.

top

The <package> element specifies single package under a repository. This tag holds configuration related to package

Attributes

AttributeRequiredDescription
idNoThe id uniquely identifies a package by GO across repositories. This attribute need not be specified. In case no value is given, server auto-generates a random UUID and assigns it as package id.
nameYesThe name uniquely identifies a package within a repository, name will be specified by user and same will be used to display on screen. Package 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 Go and the length should be less than 255 characters.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. Instead it will check for changes only when you trigger a pipeline that contains this material.

top

The <artifactStores> element is a container of many <artifactStore>.

Example

  1. <cruise>
  2. ...
  3. <artifactStores>
  4. <artifactStore id="dockerhub" pluginId="cd.go.artifact.docker.registry">
  5. <property>
  6. <key>RegistryURL</key>
  7. <value>https://index.docker.io/v1/</value>
  8. </property>
  9. <property>
  10. <key>Username</key>
  11. <value>boohoo</value>
  12. </property>
  13. <property>
  14. <key>Password</key>
  15. <value>password</value>
  16. </property>
  17. </artifactStore>
  18. </artifactStores>
  19. </cruise>

top

The <artifactStore> element specifies a global artifact store to publish/fetch external artifacts. It can contain zero or more <property> elements to specify the plugin properties.

Attributes

AttributeRequiredDescription
pluginIdYesThe ID of artifact plugin. E.g. cd.go.artifact.docker.registry.
idYesThe ID of the artifact store. ID must be a unique alphanumeric string. It can also contain -,_,.. This will be used later in the publish config

top

The <secretConfigs> element is a container of secret configurations.

There can be zero or more secret configurations.

Examples

  1. <secretConfigs>
  2. <secretConfig id="secret" pluginId="secret-plugin">
  3. ...
  4. </secretConfig>
  5. </secretConfigs>

top

The <secretConfig> element specifies a single secret configuration. It must be unique (including case) across the entire configuration.

A secretConfig should have a unique id attribute and should be associated to plugin through the pluginId attribute.

Attributes

AttributeRequiredDescription
idYesThe id is used to identify a secret config, and must be unique. The id 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.
pluginIdYesThe id of secrets plugin.

Example:

  1. <secretconfig id="secret" pluginId="secret-plugin">
  2. <configuration>
  3. <property>
  4. <key>SecretsFilePath</key>
  5. <value>/users/go/secret.db</value>
  6. </property>
  7. </configuration>
  8. </secretconfig>

top

The <description> element specifies description for the element.

Example:

  1. <description>
  2. This is a sample description.
  3. </description>

top

The <rules> element is a container for allow and deny rule. More about rules can be read from here.

Example:

  1. <rules>
  2. <allow action="refer" type="*">*</allow>
  3. <deny action="refer" type="*">*</deny>
  4. </rules>

top

The <allow> element is the rule which allows the usage of the defined secret based on action, configured type and resource.

Attributes

AttributeRequiredDescription
actionYesAction for the entity specified under attribute type.
typeYesAny GoCD entity type for which rule will be applied.

Example:

  1. <allow action="refer" type="*">*</allow>

top

The <deny> element is the rule which denies the usage of the defined secret based on action, configured type and resource.

Attributes

AttributeRequiredDescription
actionYesAction for the entity specified under attribute type.
typeYesAny GoCD entity type for which rule will be applied.

Example:

  1. <deny action="refer" type="*">*</deny>

top

The <pipelines> element is a container of pipelines.

Attributes

AttributeRequiredDescription
groupNoThe name is used to identify 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

  1. <cruise>
  2. ...
  3. <pipelines group="studios">
  4. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  5. <materials>
  6. <svn url="http://your-svn/"/>
  7. </materials>
  8. <stage name="ut">
  9. <jobs>
  10. <job name="linux">
  11. <resources>
  12. <resource>linux</resource>
  13. </resources>
  14. <tasks>
  15. <ant target="unit-test" />
  16. </tasks>
  17. </job>
  18. </jobs>
  19. </stage>
  20. </pipeline>
  21. </pipelines>
  22. </cruise>

top

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

top

The <admins> element is a permission section to specify who can administer the pipeline group. Go administrators can define roles and users in the tag.

Users and Roles defined as group admins can view and operate on all pipelines in this pipeline group. They are allowed to navigate to the admin page where they can only see and edit this pipeline group which includes creating and modifying pipelines in this group,via the Pipeline Configuration Tab. They have no permission to view or modify the Pipeline Templates even if they are used by any pipeline in this group.

Note: Go Administrators (admins) defined in security tab, can administer all pipeline groups.

Examples

Given the following configuration only admins, lqiao and any users having the role ‘studios_group_admin’.

  1. <cruise>
  2. ...
  3. <pipelines group="studios">
  4. <authorization>
  5. <admins>
  6. <user>lqiao</user>
  7. <role>studios_group_admin</role>
  8. </admins>
  9. </authorization>
  10. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  11. ......
  12. </pipeline>
  13. </pipelines>
  14. </cruise>

top

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:**Administrators (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 ‘go_readonly_member’ can see the pipeline.

  1. <cruise>
  2. ...
  3. <pipelines group="studios">
  4. <authorization>
  5. <view>
  6. <user>lqiao</user>
  7. <role>go_readonly_member</role>
  8. </view>
  9. </authorization>
  10. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  11. ......
  12. </pipeline>
  13. </pipelines>
  14. </cruise>

top

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 ‘go_core_member’ can operate the pipeline group. Only admins, lqiao and the users having the role ‘go_readonly_member’ can see the pipeline (jez and go_core_member cannot).

  1. <cruise>
  2. ...
  3. <pipelines group="studios">
  4. <authorization>
  5. <view>
  6. <user>lqiao</user>
  7. <role>go_readonly_member</role>
  8. </view>
  9. <operate>
  10. <user>lqiao</user>
  11. <user>jez</user>
  12. <role>go_core_member</role>
  13. </operate>
  14. </authorization>
  15. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  16. ......
  17. </pipeline>
  18. </pipelines>
  19. </cruise>

top

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. Go uses the pipeline name to identify the pipeline. If you change the pipeline name, you will lose the history of the pipeline.

Attributes

AttributeRequiredDescription
nameYesThe 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 Go and the length should be less than 255 characters.
labeltemplateNoBoth 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, Go 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.
lockBehaviorNoThe possible values are “none”, “lockOnFailure” or “unlockWhenFinished”.The default value is “none”. When set to “lockOnFailure”, GoCD ensures that only a single instance of a pipeline can be run at a time and the pipeline will be locked if it fails, unless it is the last stage which fails. When set to “unlockWhenFinished”, GoCD ensures that only a single instance of a pipeline can be run at a time, and the pipeline will be unlocked as soon as it finishes (success or failure), or reaches a manual stage.
templateNoThe name of the template that this pipeline references. If this is set, no stages may be defined in this pipeline.

Examples

  1. <pipelines>
  2. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}-${svn}" lockBehavior="lockOnFailure">
  3. <environmentvariables>
  4. <variable name="FOO"><value>bar</value></variable>
  5. </environmentvariables>
  6. <materials>
  7. <svn url="http://your-svn/" materialName="svn" />
  8. </materials>
  9. <stage name="ut">
  10. <jobs>
  11. <job name="linux">
  12. <resources>
  13. <resource>linux</resource>
  14. </resources>
  15. <tasks>
  16. <ant target="unit-test" />
  17. </tasks>
  18. </job>
  19. </jobs>
  20. </stage>
  21. </pipeline>
  22. </pipelines>

top

The element <params> specifies the list of parameters (Element param) elements to be used in a pipeline or a pipeline template. You can specify these under a <pipeline> and can be used anywhere inside pipeline/stage/job definition.

top

A <param> defines the parameter name that will be substituted with the paramerter value that will be substituted in a pipeline or a pipeline template.

Example:

  1. <params>
  2. <param name="COMMAND">echo</param>
  3. <param name="WORKING_DIR">/repo/branch</param>
  4. </params>

top

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

Attributes

AttributeRequiredDescription
linkYesa URL with a string ‘${ID}’. Go will replace the string ‘${ID}’ with the first matched group value at run-time.
regexYesA regex to identify the IDs. Go 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:

  1. <pipeline name="yourproject">
  2. <trackingtool link="http://your-trackingtool/yourproject/${ID}" regex="evo-(\d+)"/>
  3. ...
  4. </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, Go will take you to the web page http://your-trackingtool/yourproject/512.

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

  1. <pipeline name="yourproject">
  2. <trackingtool link="https://your-jira-server/browse/yourproject-${ID}" regex="##(\d+)"/>
  3. ...
  4. </pipeline>

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

top

The <timer> element specifies a cron-like schedule to build the pipeline.

Attributes

AttributeRequiredDescription
onlyOnChangesNoSkips scheduling if the previous run of the pipeline was with the latest material(s). This option is typically useful when automatic pipeline scheduling is turned off.

Examples

For example to run a pipeline once a night at 10pm on weekdays:

  1. <pipeline name="yourproject">
  2. <timer>0 0 22 ? * MON-FRI</timer>
  3. ...
  4. </pipeline>

Go uses the Quartz scheduler internally. For convenience we reproduce the Quartz cron documentation here:

Format

A cron expression is a string comprised of 6 or 7 fields separated by white space. Fields can contain any of the allowed values, along with various combinations of the allowed special characters for that field. The fields are as follows:

Field NameMandatory?Allowed ValuesAllowed Special Characters
SecondsYES0-59, - /
MinutesYES0-59, - /
HoursYES0-23, - /
Day of monthYES1-31, - ? / L W\
MonthYES1-12 or JAN-DEC, - /
Day of weekYES1-7 or SUN-SAT, - ? / L #
YearNOempty, 1970-2099, - * /

So cron expressions can be as simple as this: * * * * * ? or more complex, like this: 0 15 10 ? * 6L 2002-2005

Special characters

  • * (“all values”) - used to select all values within a field. For example, “*” in the minute field means “every minute”.

  • ? (“no specific value”) - useful when you need to specify something in one of the two fields in which the character is allowed, but not the other. For example, if I want my trigger to fire on a particular day of the month (say, the 10th), but don’t care what day of the week that happens to be, I would put “10” in the day-of-month field, and “?” in the day-of-week field. See the examples below for clarification.

  • - - used to specify ranges. For example, “10-12” in the hour field means “the hours 10, 11 and 12”.

  • , - used to specify additional values. For example, “MON,WED,FRI” in the day-of-week field means “the days Monday, Wednesday, and Friday”.

  • / - used to specify increments. For example, “0/15” in the seconds field means “the seconds 0, 15, 30, and 45”. And “5/15” in the seconds field means “the seconds 5, 20, 35, and 50”. You can also specify ‘/’ after the ‘’ character - in this case ‘’ is equivalent to having ‘0’ before the ‘/’. ‘1/3’ in the day-of-month field means “fire every 3 days starting on the first day of the month”.

  • L (“last”) - has different meaning in each of the two fields in which it is allowed. For example, the value “L” in the day-of-month field means “the last day of the month” - day 31 for January, day 28 for February on non-leap years. If used in the day-of-week field by itself, it simply means “7” or “SAT”. But if used in the day-of-week field after another value, it means “the last xxx day of the month” - for example “6L” means “the last friday of the month”. When using the ‘L’ option, it is important not to specify lists, or ranges of values, as you’ll get confusing results.

  • W (“weekday”) - used to specify the weekday (Monday-Friday) nearest the given day. As an example, if you were to specify “15W” as the value for the day-of-month field, the meaning is: “the nearest weekday to the 15th of the month”. So if the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify “1W” as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not ‘jump’ over the boundary of a month’s days. The ‘W’ character can only be specified when the day-of-month is a single day, not a range or list of days. The ‘L’ and ‘W’ characters can also be combined in the day-of-month field to yield ‘LW’, which translates to “last weekday of the month”.

  • # - used to specify “the nth” XXX day of the month. For example, the value of “6#3” in the day-of-week field means “the third Friday of the month” (day 6 = Friday and “#3” = the 3rd one in the month). Other examples: “2#1” = the first Monday of the month and “4#5” = the fifth Wednesday of the month. Note that if you specify “#5” and there is not 5 of the given day-of-week in the month, then no firing will occur that month. The legal characters and the names of months and days of the week are not case sensitive. MON is the same as mon.

Examples

Here are some full examples:

ExpressionMeaning
0 0 12 ?Fire at 12pm (noon) every day
0 15 10 ? Fire at 10:15am every day
0 15 10 ?Fire at 10:15am every day
0 15 10 ? Fire at 10:15am every day
0 15 10 ? 2005Fire at 10:15am every day during the year 2005
0 14 ?Fire every minute starting at 2pm and ending at 2:59pm, every day
0 0/5 14 ?Fire every 5 minutes starting at 2pm and ending at 2:55pm, every day
0 0/5 14,18 ?Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day
0 0-5 14 ?Fire every minute starting at 2pm and ending at 2:05pm, every day
0 10,44 14 ? 3 WEDFire at 2:10pm and at 2:44pm every Wednesday in the month of March.
0 15 10 ? MON-FRIFire at 10:15am every Monday, Tuesday, Wednesday, Thursday and Friday
0 15 10 15 ?Fire at 10:15am on the 15th day of every month
0 15 10 L ?Fire at 10:15am on the last day of every month
0 15 10 ? 6LFire at 10:15am on the last Friday of every month
0 15 10 ? 6LFire at 10:15am on the last Friday of every month
0 15 10 ? 6L 2002-2005Fire at 10:15am on every last friday of every month during the years 2002, 2003, 2004 and 2005
0 15 10 ? 6#3Fire at 10:15am on the third Friday of every month
0 0 12 1/5 ?Fire at 12pm (noon) every 5 days every month, starting on the first day of the month.
0 11 11 11 11 ?Fire every November 11th at 11:11am.

Pay attention to the effects of ‘?’ and ‘*’ in the day-of-week and day-of-month fields!

Notes

  • Support for specifying both a day-of-week and a day-of-month value is not complete (you must currently use the ‘?’ character in one of these fields).
  • Be careful when setting fire times between mid-night and 1:00 AM - “daylight savings” can cause a skip or a repeat depending on whether the time moves back or jumps forward.

top

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

Notes:

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

Examples

  1. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  2. <materials>
  3. <svn url="http://your-svn/"/>
  4. </materials>
  5. ...
  6. </pipeline>

Multiple materials:

  1. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}">
  2. <materials>
  3. <svn url="http://your-svn/" dest="svn-folder" />
  4. <git url="git://127.0.0.1/precommit.git" branch="1.3branch" dest="git-folder" />
  5. <hg url="http://your-hg/" dest="hg-folder" />
  6. <p4 port="10.18.3.102:1666" username="userName" password="passwd" dest="p4-folder">
  7. <view><![CDATA[
  8. //depot/dev/src... //anything/src/...
  9. ]]></view>
  10. </p4>
  11. </materials>
  12. ...
  13. </pipeline>

top

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

  1. <svn url="http://your-svn/">
  2. <filter>
  3. <ignore pattern="doc/**/*.*" />
  4. </filter>
  5. </svn>

top

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

Attributes

AttributeRequiredDescription
patternYesdefines 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:

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

Ignore everything under the folder ‘doc’.

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

Ignore files under the folder ‘doc’, excluding any subfolder.

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

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

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

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

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

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

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

top

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

Attributes

AttributeRequiredDescription
urlYesURL for the remote repository. Go supports the following protocols for subversion: http, https, svn and svn+ssh, but does not support ‘file:///’.
usernameNoThe user account for the remote repository.
passwordNoThe password for the specified user
checkexternalsNoThe 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.
destRequired if there are multiple materialsThe directory where the code will be checked out. This is relative to the sandbox of the Go Agent. Go prevents the destination folder from being outside the agent’s sandbox.
materialNameRequired if this material is referenced in pipeline labeltemplateThe 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.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. Instead it will check for changes only when you trigger a pipeline that contains this material or it receives a notification through a post-commit hook. If the same material is specified more than once in the configuration file, all of them must have the same value for autoUpdate.
invertFilterNoInverts any filter elements, turning them into whitelists. Only files that match the filter will trigger a new build.

Notes:

Go 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 ‘go’ do a command “svn update” to store the certificates in the cache permanently.

Examples:

For a Go Agent on linux with the following configuration:

  1. <pipeline name="myproduct">
  2. <materials>
  3. <svn url="http://svn-server.com/framework" dest="framework"/>
  4. <svn url="http://svn-server.com/componentOne" dest="mycomponent"/>
  5. </materials>
  6. ...
  7. </pipeline>

Go Agent will check out source code from http://svn-server.com/framework to /var/lib/go-agent/pipelines/myproduct/framwork, and from http://svn-server.com/componentOne to /var/lib/go-agent/pipelines/myproduct/mycomponent.

top

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

Notes:

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

Attributes

AttributeRequiredDescription
urlYesURL to fetch source code from the Mercurial repository. If you specify the username and password for the Mercurial repository, you should put them into the url. Mercurial supports an optional identifier after # in the url, which indicates a particular branch, tag or changeset. This option can be used to configure mercurial branches in Go.
destOnly for multiple materialsThe directory where the code will be checked out. This is relative to the sandbox of the Go Agent. Go prevents the destination folder from being outside the agent’s sandbox.
materialNameRequired if this material is referenced in pipeline labeltemplateThe 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.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. Instead it will check for changes only when you trigger a pipeline that contains this material. If the same material is specified more than once in the configuration file, all of them must have the same value for autoUpdate.
invertFilterNoInverts any filter elements, turning them into whitelists. Only files that match the filter will trigger a new build.

Examples

  1. <pipeline name="yourproject">
  2. <materials>
  3. <hg url="http://username:password@your-hg/"/>
  4. </materials>
  5. ...
  6. </pipeline>

Specifying a mercurial branch.

  1. <pipeline name="yourproject_branch">
  2. <materials>
  3. <hg url="http://username:password@your-hg##branch_name"/>
  4. </materials>
  5. ...
  6. </pipeline>

Note that # needs to be escaped with another # - hence the ## in the url above.

top

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

Notes:

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

Attributes

AttributeRequiredDescription
portYesPerforce 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.
usernameNoPerforce username to use.
passwordNoPassword for the specified user.
useTicketsNoSet to true to work with perforce tickets. Go 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.
destOnly for multiple materialsThe directory where the code will be checked out. This is relative to the sandbox of the Go Agent. Go prevents the destination folder from being outside the agent’s sandbox.
viewYesValid Perforce view. The view should be a sub-element of P4. Click here to see details about VIEW of Perforce.
materialNameRequired if this material is referenced in pipeline labeltemplateThe 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.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. Instead it will check for changes only when you trigger a pipeline that contains this material. If the same material is specified more than once in the configuration file, all of them must have the same value for autoUpdate.
invertFilterNoInverts any filter elements, turning them into whitelists. Only files that match the filter will trigger a new build.

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 Go configuration, Go will overwrite them before running p4.

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

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

Go creates a p4 client to check out files into its sandbox with the ‘clobber’ option set. This means, during material update all writable-but-unopened files in the workspace would be overwritten on the agent. All other options use default values as defined by Perforce. Client name is generated automatically by Go. Hence, you can use anything as ‘clientname’ on the right-hand side in view mapping. The client name format is: cruise-[hostname]-[pipeline name]-[a random hash code], for example “cruise-myhostname-mypipelinename-wOaJ9kjpfgOLQCncki19ikXt5Q”. THE GO_P4_CLIENT environment variable will have the client name used. This variable can be used in scripts to get the client name

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

  1. <pipeline name="perforce-example"/>
  2. <materials>
  3. <p4 port="10.18.3.102:1666" username="userName" password="passwd">
  4. <view><![CDATA[
  5. //depot/dev/src... //anything/src/...
  6. //depot/dev/test... //anything/test/...
  7. //depot/dev/main/docs/... //anything/docs/...
  8. ]]></view>
  9. </p4>
  10. </materials>
  11. ...
  12. </pipeline>

top

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

Notes:

git versions 1.7 and above are supported by Go.

If ‘branch’ is defined, Go will check out the specified branch. Otherwise, Go will check out the master branch.

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

msysGit on Windows has a defect which causes an error when using Go. Please ensure to use a build which fixes this.

While installing msysGit On Windows machines for Go server or agents, please choose Option iii, namely Run Git and included UNIX tools from windows command prompt

If you are using git through SSH on windows, please ensure that the HOME user environment variable is set to the full path of the parent directory where the .ssh/ directory is located.

Attributes

AttributeRequiredDescription
urlYesGIT URL for the repository.
branchNoa branch name in the repository.
shallowCloneNoAdd a —depth=N option to git cloning command on Go agent. Shallow clone truncates history to latest revisions, thus helps accelerating clone operation for repositories with long history. Cloning depth is dynamically calculated to ensure revisions from GO_FROM_REVISION to GO_TO_REVISION are included in the cloned repository.
destOnly for multiple materialsThe directory under the sandbox of Go Agent. Go will check out the source code into this directory.
materialNameRequired if this material is referenced in pipeline labeltemplateThe 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.
autoUpdateNoBy default Go polls the repository for changes automatically. If autoUpdate is set to false then Go will not poll the repository for changes. Instead it will check for changes only when you trigger a pipeline that contains this material. If the same material is specified more than once in the configuration file, all of them must have the same value for autoUpdate.
invertFilterNoInverts any filter elements, turning them into whitelists. Only files that match the filter will trigger a new build.

Examples are:

  1. <pipeline name="yourproject">
  2. <materials>
  3. <git url="git://127.0.0.1/precommit.git" branch="1.3branch"/>
  4. </materials>
  5. ...
  6. </pipeline>
  1. <pipeline name="yourproject">
  2. <materials>
  3. <git url="http://ccegit:pst@goserver.yourcompany.com/httpgit.git" />
  4. </materials>
  5. ...
  6. </pipeline>

top

The <tfs> element specifies the location of your code base in a TFS Source repository.

Attributes

AttributeRequiredDescription
URLYesURL for the Collection on the TFS Server.
DomainNoDomain name for TFS authentication credentials.
UsernameYesUsername of the account to access the TFS collection.
PasswordYesPassword of the account to access the TFS collection.
Project PathYesThe project path within the TFS collection.
destOnly for multiple materialsThe directory where the code will be checked out. This is relative to the sandbox of the Go Agent. Go prevents the destination folder from being outside the agent’s sandbox.
invertFilterNoInverts any filter elements, turning them into whitelists. Only files that match the filter will trigger a new build.

Examples are:

  1. <pipeline name="webproject">
  2. <materials>
  3. <tfs url="http://10.21.3.210:8080/tfs/New" domain="DOMAIN" username="jim" password="as802nsk9==" projectPath="$/webapp" />
  4. </materials>
  5. ...
  6. </pipeline>
  1. <pipeline name="myproject">
  2. <materials>
  3. <tfs url="http://tfshost.tw.com:8080/tfs/DefaultCollection" domain="DOMAIN" username="jim" password="as802nsk9==" projectPath="$/webapp/component/branch" />
  4. </materials>
  5. ...
  6. </pipeline>

top

The <package> element refers to package which is defined as part of repositories configuration.

Attributes

AttributeRequiredDescription
refYesThe ref tag holds the id of the package

Example

  1. <cruise>
  2. ...
  3. <repositories>
  4. <repository id="repo-id" name="repo-name">
  5. <pluginConfiguration id="plugin-id" version="plugin-version" />
  6. <configuration>
  7. <property>
  8. <key>property-name</key>
  9. <value>property-value</value>
  10. </property>
  11. ...
  12. </configuration>
  13. <packages>
  14. <package id="1234-12242-232312" name="sample-package" >
  15. <configuration>
  16. <property>
  17. <key>property-name</key>
  18. <value>property-value</value>
  19. </property>
  20. ...
  21. </configuration>
  22. </package>
  23. </packages>
  24. </repository>
  25. </repositories>
  26. <pipelines name="webproject">
  27. ...
  28. <pipeline name="webproject">
  29. <materials>
  30. <package ref="1234-12242-232312" />
  31. </materials>
  32. ...
  33. </pipeline>
  34. ...
  35. </pipelines>
  36. </cruise>

top

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.

Note that you can not specify two (or more) dependencies for the same upstream pipeline.

Attributes

AttributeRequiredDescription
pipelineNameYesThe name of a pipeline that this pipeline depends on.
stageNameYesThe name of a stage which will trigger this pipeline once it is successful.
materialNameBy default the materialName is the name of the upstream pipeline (the pipelineName). This is required if this material is referenced in pipeline labeltemplateThe 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.
ignoreForSchedulingNo (false by default)When set to true, the pipeline will not be automatically scheduled for changes to this material. However, when the pipeline is triggered (either by another material, or a manual or timer trigger), it will always pick up the latest available version of this material

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:

  1. <pipeline name="Server">
  2. <materials>
  3. <pipeline pipelineName="commonLib1" stageName="distStage"/>
  4. <pipeline pipelineName="commonLib2" stageName="pkgStage"/>
  5. </materials>
  6. ...
  7. </pipeline>
  8. <pipeline name="Client">
  9. <materials>
  10. <pipeline pipelineName="commonLib1" stageName="distStage"/>
  11. </materials>
  12. ...
  13. </pipeline>

If the Server pipeline needs to be triggered only when commonLib2 changes, the ignoreForScheduling flag can be set for the commonLib1 material:

  1. <pipeline name="Server">
  2. <materials>
  3. <pipeline pipelineName="commonLib1" stageName="distStage" ignoreForScheduling="true"/>
  4. <pipeline pipelineName="commonLib2" stageName="pkgStage"/>
  5. </materials>
  6. ...
  7. </pipeline>

top

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

AttributeRequiredDescription
nameYesThe 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.
fetchMaterialsNo (Default: true)Perform material updates or checkouts on the agent. Set this attribute to false to skip this operation.
cleanWorkingDirNo (Default: false)Remove all files/directories in the working directory on the agent. By default this operation is skipped.
artifactCleanupProhibitedNo (Default: false)Never cleanup artifacts for this stage, if purging artifacts is configured at the Server Level.

Examples

  1. <pipeline name="yourproject">
  2. ...
  3. <stage name="ut">
  4. <environmentvariables>
  5. <variable name="FOO"><value>bar</value></variable>
  6. </environmentvariables>
  7. <jobs>
  8. <job name="linux">
  9. <resources>
  10. <resource>linux</resource>
  11. </resources>
  12. <tasks>
  13. <ant target="unit-test" />
  14. </tasks>
  15. </job>
  16. </jobs>
  17. </stage>
  18. </pipeline>

top

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

  1. <stage name="ut">
  2. <jobs>
  3. <job name="linux">
  4. <resources>
  5. <resource>linux</resource>
  6. </resources>
  7. <tasks>
  8. <ant target="unit-test" />
  9. </tasks>
  10. </job>
  11. </jobs>
  12. </stage>

top

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

A job can also be associated with a set of <resources> or an elastic profile through the elasticProfileId attribute. Resources are used to match a Job to an Agent. ElasticProfileId is used to match a job to an Elastic Agent. An Agent can run a Job if it has all the resources or elasticProfileId that the Job specifies.

A job cannot have both resources as well as elasticProfileId. If a Job has no resources then it can be built by any Agent (But not by an elastic agent)

Attributes

AttributeRequiredDescription
nameYesThe 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.
runOnAllAgentsNoIf set to ‘true’ then the Job will run on all agents that can run the job.
runInstanceCountNoIf set to ‘x’ (integer) then ‘x’ instances of Job will be spawned during scheduling. Environment variables GO_JOB_RUN_INDEX (with values 1-x for every Job) and GO_JOB_RUN_COUNT (with value x for each Job) will be exposed to each task of Job.
timeoutNoA job can be configured to time out if it does not generate any console output for a period of time. Use this attribute to define the timeout value in minutes. Define timeout as 0 if the job should never time out. If the attribute is not defined, the default <server> level timeout behaviour will apply.
elasticProfileIdNoA job can be configured to run on an elastic agent by specifying this attribute, which maps to the id of an existing <agentProfile>. MUST NOT be specified along with resources.

Examples

  1. <job name="linux">
  2. <environmentvariables>
  3. <variable name="FOO">
  4. <value>bar</value>
  5. </variable>
  6. </environmentvariables>
  7. <resources>
  8. <resource>linux</resource>
  9. </resources>
  10. <tasks>
  11. <ant target="unit-test" />
  12. </tasks>
  13. </job>
  1. <job name="run-upgrade" runOnAllAgents="true" timeout='30' elasticProfileId="aws.small">
  2. <tasks>
  3. <ant target="upgrade" />
  4. </tasks>
  5. </job>
  1. <job name="run-upgrade" runInstanceCount="5" timeout='30'>
  2. <resources>
  3. <resource>linux</resource>
  4. </resources>
  5. <tasks>
  6. <ant target="upgrade" />
  7. </tasks>
  8. </job>

top

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

  1. <job name="linux">
  2. <resources>
  3. <resource>jdk5</resource>
  4. <resource>tomcat5</resource>
  5. <resource>mercurial</resource>
  6. </resources>
  7. </job>

top

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.

Validations:

Resources are case-insensitive. A resource name can contain alphanumeric characters, hyphens (-), spaces, periods (.) and pipes (|).

Example:

  1. <resources>
  2. <resource>jdk5</resource>
  3. <resource>tomcat5</resource>
  4. <resource>mercurial</resource>
  5. </resources>

top

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

AttributeDescription
GOSERVER_URLThe base URL for the server, including ‘/go’. For example: https://localhost:8154/go
GO_PIPELINE_NAMEThe name of the pipeline to which the job belongs to
GO_PIPELINE_LABELThe label of the pipeline to which the job belongs to
GO_STAGE_NAMEThe name of the stage to which the job belongs to
GO_STAGE_COUNTERThe re-run counter of the stage to which the job belongs to
GO_JOB_NAMEThe name of the job that is being run
GO_DEPENDENCY_LABEL <upstreampipeline_name><upstreamstage_name>The label of the upstream pipeline which triggered the pipeline which the job belongs to. For example: ‘GO_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: GO_DEPENDENCY_LABEL_PIPELINE_FOO_STAGE_FOO.
GO_TO_REVISION<materialname>The lastest revision in modifications that the build running against for each configured SCM material.
GO_FROM_REVISION<material_name>The earlist revision in modifications that the build running against for each configured SCM material.

Examples

  1. <job name="linux">
  2. <tasks>
  3. <ant target="unit-test" />
  4. </tasks>
  5. </job>

top

Specifies an Ant build to run. Ant is assumed to be present from the command line on the agent. Go 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

AttributeRequiredDescription
buildfileNoPath to Ant build file. If not specified, the path defaults to ‘build.xml’.
targetNoAnt target(s) to run. If not specified, the target defaults to ‘default’
workingdirNoThe directory from where Ant is invoked

Examples

  • Invoke Ant, specifying a set of targets to run:

    1. <tasks>
    2. <ant target="-Drun=all clean.ivy.localivy clean ft.long_running"/>
    3. </tasks>
  • Invoke Ant in a specific working directory with a set of targets:

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

top

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

AttributeRequiredDescription
commandYesThe command or script to be executed, relative to the working directory
argsNoSet 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.
workingdirNoThe directory in which the script or command is to be executed. Note that this directory is relative to the directory where the agent checks out the materials.

Examples

  • Invoke ruby, specifying the working directory as tools/my-ruby-tool and executing the ruby script backup.rb.

    1. <tasks>
    2. <exec command="/usr/local/bin/ruby" args="backup.rb" workingdir="tools/my-ruby-tool"/>
    3. </tasks>

top

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, Go 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)

Examples

  • Echo something on Windows:

    1. <exec command="cmd">
    2. <arg>/c</arg>
    3. <arg>echo</arg>
    4. <arg>something to print out</arg>
    5. </exec>
  • Run command with pipe character in arguments:

    1. <exec command="MsBuild">
    2. <arg>D:\projects\project\project-8.sln</arg>
    3. <arg>/REBUILD</arg>
    4. <arg>/CFG="Release_99|Win32"</arg>
    5. </exec>

top

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

AttributeRequiredDescription
buildfileNoPath 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.
targetNoNAnt target(s) to run. If not specified, defaults to the default target of the build file.
workingdirNoThe directory from where NAnt is invoked
nantpathNoPath of the directory in which NAnt is installed. By default Go 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:

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

top

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

AttributeRequiredDescription
buildfileNoPath to Rake file. If not specified, the path defaults to ‘rakefile’. The path cannot start from ‘.’
targetNoRake target(s) to run. If not specified, defaults to the default target of the build file
workingdirNoThe directory from where Rake is invoked

Examples

Invoke rake, specifying a set of targets to run:

  1. <tasks>
  2. <rake buildfile="rakefile" target="smoke-test"/>
  3. </tasks>

top

Fetch artifacts from:

  • 1. previous stages in the same pipeline, or
  • 2. stages of pipelines that this pipeline depends on, directly or indirectly (ancestor pipelines).

When pointed to parent/ancestor pipeline, fetch task can pull artifacts from the upstream-stage or stages before it. This restriction has been introduced in 12.2. Stages after the upstream stage can not be fetched from, because they may not be complete when the fetch call executes.

All file paths specified are relative to the pipeline working directory.

Attributes

AttributeRequiredDescription
artifactOriginYesIndicates where the artifact needs to be pulled from. Supported values are gocd and external. gocd implies that the artifact needs to be fetched from the gocd server, external implies that the artifact must be fetched from an external artifact store.
pipelineNoThis value can either be: 1. the name of upstream pipeline on which the pipeline of the job depends on. The pipeline should be added as a dependency under <materials>, or 2. the hierarchy of an ancestor pipeline of the current pipeline. Example, The value “BuildPipeline/AcceptancePipeline” denotes that the fetch task attempts to fetch artifacts from its ancestor ‘BuildPipeline’. The given hierarchy denotes that the current pipeline depends on ‘AcceptancePipeline’ which in turn depends on ‘BuildPipeline’ using the dependency material definition given under materials. Defaults to current pipeline if not specified.
stageYesThe name of the stage to fetch artifacts from
jobYesThe name of the job to fetch artifacts from
srcdirOne of srcdir/srcfile if artifact origin is gocdThe path of the artifact directory of a specific job, relative to the sandbox directory. If the directory does not exist, the job is failed. Should be specified if artifactOrigin is gocd.
srcfileOne of srcdir/srcfile if artifact origin is gocdThe path of the artifact file of a specific job. Should be specified if artifactOrigin is gocd.
destNoThe 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. Should be specified if artifactOrigin is gocd.
artifactIdYes, if artifact origin is externalThe id of the external artifact that is published by the plugin in the upstream job. Should be specified if the artifact origin is external.
configurationNo‘A list of key-value pairs which defines the plugin configuration. Should be specified if artifact origin is external.

Note: If the file does not exist, the job will fail. Go will not fetch the artifact again if it has not changed. The directory path is relative to the pipeline working directory. |

Example:

  1. Fetch all artifacts in the directory ‘pkg’ from the previous stage in the same pipeline and put them under the directory ‘lib’

    1. <pipelines>
    2. <pipeline name="go">
    3. ...
    4. <stage name="dev">
    5. <jobs>
    6. <job name="unit">
    7. <artifacts>
    8. <artifact type="build" src="target/deployable.jar" dest="pkg"/>
    9. <artifact type="external" id="artifact_jar" storeId="dummy-s3">
    10. <configuration>
    11. <property>
    12. <key>Filename</key>
    13. <value>target/deployable.jar</value>
    14. </property>
    15. </configuration>
    16. </artifact>
    17. </artifacts>
    18. </job>
    19. </jobs>
    20. </stage>
    21. <stage name="ft">
    22. <jobs>
    23. <job name="functional">
    24. <tasks>
    25. <fetchartifact artifactOrigin="gocd" stage="dev" job="unit" srcdir="pkg" dest="lib"/>
    26. <fetchartifact artifactOrigin="external" stage="dev" job="unit" artifactId="artifact_jar">
    27. <configuration>
    28. <property>
    29. <key>dest_on_agent</key>
    30. <value>release_candidate.jar</value>
    31. </property>
    32. </configuration>
    33. </fetchartifact>
    34. </tasks>
    35. </job>
    36. </jobs>
    37. </stage>
    38. </pipeline>
    39. </pipelines>
  2. Fetch a single artifact from a stage in the upstream pipeline ‘framework’ and put it under the directory ‘lib’

    1. <pipeline name="go">
    2. <materials>
    3. <pipeline name="framework" stage="ft"/>
    4. </materials>
    5. <stage name="dev">
    6. <jobs>
    7. <job name="unit">
    8. <tasks>
    9. <fetchartifact origin="gocd" pipeline="framework" stage="dev" job="unit"
    10. srcfile="pkg/deployable.jar" dest="lib" />
    11. </tasks>
    12. </job>
    13. </jobs>
    14. </stage>
    15. </pipeline>
  3. Fetch a single artifact from a stage in an ancestor pipeline ‘Build’ and put it under the directory ‘pkg’

    1. <pipeline name="deploy">
    2. <materials>
    3. <pipeline name="acceptance" stage="ft"/>
    4. </materials>
    5. <stage name="deply-pkg">
    6. <jobs>
    7. <job name="deploy-win">
    8. <tasks>
    9. <fetchartifact origin="gocd" pipeline="build" stage="dist" job="create-installer"
    10. srcfile="installers/deployable-setup.exe" dest="installer" />
    11. </tasks>
    12. </job>
    13. </jobs>
    14. </stage>
    15. </pipeline>

top

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

AttributeRequiredDescription
statusYesThe status is the job’s current status. The value should be one of ‘passed’, ‘failed’ or ‘any’.

Notes:

<runif> can also be defined under <exec> task even if <exec> has some <arg>s e.g.

  1. <exec command="echo">
  2. <arg value="test" />
  3. <runif status="passed" />
  4. </exec>

Examples

Given the tasks in a job is following:

  1. <tasks>
  2. <ant buildfile="build.xml" target="complie-test-source"/>
  3. <fetchartifact origin="gocd" pipeline="my_app" stage="dist" job="package-artifact" srcdir="pkg">
  4. <runif status="passed"/>
  5. </fetchartifact>
  6. <exec command="./copy_error_log_to_someplace" >
  7. <runif status="failed"/>
  8. </exec>
  9. </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.

top

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 be killed
  • 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.

  1. <tasks>
  2. <ant target="start_server">
  3. <oncancel>
  4. <ant target="kill_server" />
  5. </oncancel>
  6. </ant>
  7. </tasks>

top

<artifacts> specifies what files the agent will publish to the server or an external artifact store.

Examples

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/deployable.jar" dest="pkg"/>
  4. <artifact type="test" src="target/junit-output" dest="junit"/>
  5. <artifact type="external" id="docker-image" storeId="dockerhub">
  6. <configuration>
  7. <property>
  8. <key>Image</key>
  9. <value>gocd/gocd-demo</value>
  10. </property>
  11. <property>
  12. <key>Tag</key>
  13. <value>v${GO_PIPELINE_COUNTER}</value>
  14. </property>
  15. </configuration>
  16. </artifact>
  17. </artifacts>
  18. </job>

top

Publish build or test artifacts to the artifact repository for the job. The src attribute should point towards a folder that contains the test output files. Go will use these to generate a test report if the artifact type is test. 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

AttributeRequiredDescription
typeYesType can be either build or test. This identifies the type of artifact that is uploaded to the GoCD server
srcYes, if type is build or testThe file or folders to publish to the server. Go 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. Should be specified if type is build or test
destNoThe 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. Should be specified if type is build or test
idYes, if type is externalThe artifact id for an external artifact. This id can be used later in a downstream fetch task. Should be specified if type is external.
storeIdYes, if type is externalThe artifact store id referencing an existing global artifact store. Should be specified if type is external.
configurationNo‘A list of key-value pairs which defines the plugin configuration. Should be specified if type is external.

You can use wildcards to specify which files to upload to the go server in case of build or test artifacts. 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 for build artifact

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/deployable.jar" dest="pkg"/>
  4. </artifacts>
  5. </job>
  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/**/*Test.xml" dest="pkg"/>
  4. </artifacts>
  5. </job>

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

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/**/*.xml" />
  4. </artifacts>
  5. </job>

top

Examples for test artifact

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="test" src="target/junit-output" dest="junit"/>
  4. </artifacts>
  5. </job>

Examples for external artifact

  1. <job name="build_image">
  2. <artifacts>
  3. <artifact type="external" id="docker-image" storeId="dockerhub">
  4. <configuration>
  5. <property>
  6. <key>Image</key>
  7. <value>gocd/gocd-demo</value>
  8. </property>
  9. <property>
  10. <key>Tag</key>
  11. <value>v${GO_PIPELINE_COUNTER}</value>
  12. </property>
  13. </configuration>
  14. </artifact>
  15. </artifacts>
  16. </job>

top

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:

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/jcoverage" dest="Jcoverage"/>
  4. </artifacts>
  5. <tabs>
  6. <tab name="coverage" path="Jcoverage/index.html"/>
  7. </tabs>
  8. </job>

top

Define a tab with specific name and artifact to show.

Attributes

AttributeRequiredDescription
nameYesThe name of the tab. If should be unique in that job.
pathYesThe relative path of a file in the artifact repository of the job.

Example:

Given some coverage information 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.

  1. <job name="unit">
  2. <artifacts>
  3. <artifact type="build" src="target/jcoverage" dest="Jcoverage"/>
  4. </artifacts>
  5. <tabs>
  6. <tab name="coverage" path="Jcoverage/index.html"/>
  7. </tabs>
  8. </job>

top

Specifies how a stage should be triggered. <approval> of type ‘manual’ or ‘success’ 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, stage details page or through RESTful url.

Attributes

AttributeRequiredDescription
typeYesEither ‘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.
allowOnlyOnSuccessNoSetting this attribute to ‘true’ will ensure that the stage can triggered only if the previous stage (if any) has succeeded.

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.
  • If attribute allowOnlyOnSuccess is not specified, then the behaviour is same as false.

Example:

  1. <stage name="ut">
  2. <approval type="manual" allowOnlyOnSuccess="true"/>
  3. ...
  4. </stage>

top

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

Examples

  1. <approval type="manual">
  2. <authorization>
  3. <user>lqiao</user>
  4. <role>go_admins</role>
  5. </authorization>
  6. </approval>
  1. <approval type="success">
  2. <authorization>
  3. <user>lqiao</user>
  4. <role>go_admins</role>
  5. </authorization>
  6. </approval>

top

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

top

Allows you to provide a template for pipeline definition

Attributes

AttributeRequiredDescription
nameYesIdentifier for the pipeline template

Examples

  1. <cruise>
  2. ...
  3. <pipelines group="studios" >
  4. <pipeline name="yourproject" template="project-template" >
  5. <materials>
  6. <svn url="http://your-svn/"/>
  7. </materials>
  8. </pipeline>
  9. </pipelines>
  10. <templates>
  11. <pipeline name="project-template">
  12. <authorization>
  13. <admins>
  14. <user>jez</user>
  15. </admins>
  16. </authorization>
  17. <stage name="ut">
  18. <jobs>
  19. <job name="linux">
  20. <resources>
  21. <resource>linux</resource>
  22. </resources>
  23. <tasks>
  24. <ant target="unit-test" />
  25. </tasks>
  26. </job>
  27. </jobs>
  28. </stage>
  29. </pipeline>
  30. </templates>
  31. </cruise>

top

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

top

Allows you to group a set of agents and pipelines together for exclusive use.

Attributes

AttributeRequiredDescription
nameYesIdentifier for an environment

Examples

  1. <cruise>
  2. ...
  3. <pipelines group="studios" />
  4. <pipeline name="yourproject" labeltemplate="foo-1.0.${COUNT}" >
  5. ...
  6. </pipeline>
  7. </pipelines>
  8. <environments>
  9. <environment name="UAT">
  10. <environmentvariables>
  11. <variable name="FOO"><value>bar</value></variable>
  12. </environmentvariables>
  13. <pipelines>
  14. <pipeline name="yourproject"/>
  15. </pipelines>
  16. </environment>
  17. </environments>
  18. </cruise>

top

<environmentvariables> specifies the variables to pass to jobs and their tasks. You can specify these on a <pipeline>, <stage>, <job> or an <environment>. If the same environment variable is definied either on the agent where the job runs or on the pipeline/stage/environment of the job, the precedence is in the order <job>, <stage>, <pipeline>, <environment> and the system environment variable. For example, variable “FOO” defined in a job overrides the variable definied in the job’s stage.

top

A <variable> defines the variable name and property value that will be passed to a job. It will be set on the system environment when the job is run. The value can be include multiple lines or CDATA. Note that the behaviour is operating system dependent. Your operating system may not allow certain variable names and/or values.

Attributes

AttributeRequiredDescription
nameYesIdentifier for an environment variable
secureNoThis attribute is applicable only at the pipeline level and when set to true, encrypts the environment variable value.

Example:

  1. <environmentvariables>
  2. <variable name="FOO"><value>bar</value></variable>
  3. <variable name="MULTIPLE_LINES"><value>multiplelines</value></variable>
  4. <variable name="COMPLEX"><value>![CDATA[This has very <complex> data]]</value></variable>
  5. </environmentvariables>

top

The <pipelines> element inside the <environment> element specifies the set of pipelines that it references.

top

References a pipeline to be associated with this environment.

Attributes

AttributeRequiredDescription
nameYesIdentifier to an pipeline (must exist in the config file).

Examples

  1. <environment name="UAT">
  2. <pipelines>
  3. <pipeline name="yourproject"/>
  4. </pipelines>
  5. </environment>

top