Introduction
Welcome to the GoCD API! You can use our API to access GoCD API endpoints, which can get information about the server’s configuration and build history. In addition it can be used to update configuration and execute builds.
We currently provide language bindings in Shell! You can view code examples on the right-hand side of the page.
All APIs SHOULD be accessed from https://go-server-url:8154/go/api. All data SHOULD be sent and recieved as JSON, specifically application/vnd.go.cd[.VERSION]+json. You may access the APIs over plain text, but for security reasons we suggest that you use TLS.
API versions
It is recommended to explicitly request the version of an API via the Accept: application/vnd.go.cd[.VERSION]+json header, with an appropriate version. Some examples are:
Accept: application/vnd.go.cd.v1+json
Accept: application/vnd.go.cd.v2+json etc
Each documented API endpoint shows the correct version to use in its usage documentation.
Beginning with GoCD version 19.8, it is possible to omit the version number by specifying Accept: application/vnd.go.cd+json. This will render the latest version.
If you specify an unsupported Accept header, GoCD will respond with a status code 404 error message The url you are trying to reach appears to be incorrect.
GoCD Deprecated APIs
GoCD may deprecate APIs for any of the following reasons:
- Use of the API is unsafe.
- An improved alternative API is available.
- Breaking changes to the API are expected in a future release(s).
In order to convey the API deprecation information to the API consumers, GoCD adds following deprecation headers for a deprecated API:
X-GoCD-API-Deprecated-In: This Response header denotes the GoCD Version when the API was deprecated.X-GoCD-API-Removal-In: This Response header denotes the GoCD Version when the API will be removed.X-GoCD-API-Deprecation-Info: This Response header provides a link to the GoCD API deprecation documentation.Link: This Response header has following 3 parts:Link: The successor API link.Accept Header: The successor API’s version Accept Header.rel: The relation of the link with the deprecated API. This field has a fixed valuesuccessor-versiondenoting the specified link and the accept header is the successor of the deprecated API.
Warning: This Response header has following 3 parts:Code: The warning code. This field has a fixed value 299. Know more about warn-code at MDN.Agent: The warning agent. This field represents the GoCD version adding the warning in the formatGoCD/<GoCD_Vesion>Message: The warning message.
Revoking deprecations
Occasionally, the deprecation of an API may be modified/reversed for some unavoidable reasons. In such situations, the subsequent GoCD releases will provide the updated deprecated headers with information relevant to the decision. Refer changelog section for the list of deprecated APIs.
Authentication
All APIs require you to authenticate yourself using your username and password. Starting with version 19.2.0 of GoCD, users may also use a bearer token to authenticate. If authentication fails, GoCD server may return status codes 401, 403 or 404.
Bearer token authentication
Available since v19.2.0.
To authorize, use this code:
# With shell, you can just pass the correct header with each request
$ curl 'https://ci.example.com/go/api/current_user' \
-H 'Authorization: bearer YOUR_TOKEN' \
-H 'Accept: application/vnd.go.cd.v1+json'
Make sure to replace the
YOUR_TOKENthe API token you use to access the GoCD server. The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"current_user": {
"href": "https://ci.example.com/go/api/current_user"
},
"self": {
"href": "https://ci.example.com/go/api/users/username"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "username",
"display_name": "username",
"enabled": true,
"email": "demo@example.com",
"email_me": true,
"checkin_aliases": []
}
To generate an access token, navigate to https://ci.example.com:8154/go/access_tokens, or use the access token API.
Basic authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
$ curl 'https://ci.example.com/go/api/current_user' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
Make sure to replace the
usernameandpasswordwith the username and password that you use to access the GoCD server. The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"current_user": {
"href": "https://ci.example.com/go/api/current_user"
},
"self": {
"href": "https://ci.example.com/go/api/users/username"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "username",
"display_name": "username",
"enabled": true,
"email": "demo@example.com",
"email_me": true,
"checkin_aliases": []
}
To use Basic Authentication with the GoCD API, simply send the username and password associated with the account.
section_marker_placeholder:Config
Artifact Store
The artifact store API allows admin users to define and manage configuration of external artifact repository. The artifact plugin will use the artifact store config to upload artifact to an external repository.
The artifact store object
Available since v18.7.0.
{
"id": "docker",
"plugin_id": "cd.go.artifact.docker",
"properties": [
{
"key": "RegistryURL",
"value": "docker-registry-url"
}
]
}
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the artifact store. |
plugin_id |
String | The plugin identifier of the artifact plugin. |
properties |
Array | The list of configuration properties that represent the configuration of this artifact store. |
Get all artifact stores
$ curl 'https://ci.example.com/go/api/admin/artifact_stores' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores"
},
"doc" : {
"href" : "https://api.gocd.org/current/#artifact_stores"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
}
},
"_embedded" : {
"artifact_stores" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/hub.docker"
},
"doc" : {
"href" : "https://api.gocd.org/current/#artifact_stores"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
}
},
"id" : "hub.docker",
"plugin_id" : "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"encrypted_value" : "AES:tdfTtYtIUSAF2JXJP/3YwA==:43Kjidjuh42NHKisCAs/BQ=="
} ]
} ]
}
}
Lists all available artifact stores.
Available since v18.7.0.
HTTP Request
GET /go/api/admin/artifact_stores
Returns
An array of artifact store object.
Get an artifact store
$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "fff30fd05db389acded4e993c1ecd5a4"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/hub.docker"
},
"doc" : {
"href" : "https://api.gocd.org/current/#artifact_stores"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
}
},
"id" : "hub.docker",
"plugin_id" : "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"encrypted_value" : "AES:tdfTtYtIUSAF2JXJP/3YwA==:43Kjidjuh42NHKisCAs/BQ=="
} ]
}
Gets an artifact store for specified id.
Available since v18.7.0.
HTTP Request
GET /go/api/admin/artifact_stores/:storeId
Returns
Create an artifact store
$ curl 'https://ci.example.com/go/api/admin/artifact_stores' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "docker",
"plugin_id": "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"value" : "badger"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e239974f09be2d88565c584c01ba0954"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/docker"
},
"doc" : {
"href" : "https://api.gocd.org/current/#artifact_stores"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
}
},
"id" : "docker",
"plugin_id" : "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"encrypted_value" : "AES:UbZMF/cQZCcywknuzW6r4Q==:Qbz5so1iz3WS2a4FSW775A=="
} ]
}
Creates an artifact store
Available since v18.7.0.
HTTP Request
POST /go/api/admin/artifact_stores
Returns
Update an artifact store
$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
-u 'admin:badger' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "e239974f09be2d88565c584c01ba0954"' \
-X PUT -d '{
"id": "docker",
"plugin_id": "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"value" : "new_password"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "fe2670c76227d5d96f76007f3803dc68"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/docker"
},
"doc" : {
"href" : "https://api.gocd.org/current/#artifact_stores"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/artifact_stores/:id"
}
},
"id" : "docker",
"plugin_id" : "cd.go.artifact.docker.registry",
"properties" : [ {
"key" : "RegistryURL",
"value" : "https://your_docker_registry_url"
}, {
"key" : "Username",
"value" : "admin"
}, {
"key" : "Password",
"encrypted_value" : "AES:yIow3jqZjP+mWuKubdwhTw==:safdVBEoe6sIjuuILGP53g=="
} ]
}
Update some attributes of an artifact store.
Available since v18.7.0.
HTTP Request
PUT /go/api/admin/artifact_stores/:storeId
Returns
The updated The artifact store object..
Delete an artifact store
$ curl 'https://ci.example.com/go/api/admin/artifact_stores/docker' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message": "The artifactStore 'docker' was deleted successfully."
}
Deletes the artifact store.
Available since v18.7.0.
HTTP Request
DELETE /go/api/admin/artifact_stores/:storeId
Returns
A message if the artifact store is deleted or not.
Artifacts Config
The artifacts config API allows admins to configure the artifacts directory and purge settings.
The Artifacts Config Object
Available since v19.11.0.
| Attribute | Type | Description |
|---|---|---|
artifacts_dir |
String | This directory is where GoCD will store its information, including artifacts published by jobs. You can use an absolute path or a relative path which will take the server installed directory as the root. |
purge_settings |
Object | The attributes for purge settings. |
The Purge Settings Object
Available since v19.11.0.
| Attribute | Type | Description |
|---|---|---|
purge_start_disk_space |
Number | Purge artifacts when disk space is lower than purge_start_disk_space GB. |
purge_upto_disk_space |
Number | Purge artifacts till available disk space is greater than purge_upto_disk_space GB. This attribute must be defined if purge_start_disk_space is defined. |
Get artifacts Config
$ curl 'https://ci.example.com/go/api/admin/config/server/artifact_config' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Etag: "17f5a9edf150884e5fc4315b4a7814cd"
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#artifacts-config"
},
"self" : {
"href" : "http://ci.example.com/go/api/admin/config/server/artifact_config"
}
},
"artifacts_dir" : "foo",
"purge_settings" : {
"purge_start_disk_space" : 10.0,
"purge_upto_disk_space" : 20.0
}
}
Available since v19.11.0.
HTTP Request
GET /go/api/admin/config/server/artifact_config
Returns
Update artifacts Config
$ curl 'https://ci.example.com/go/api/admin/config/server/artifact_config' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "17f5a9edf150884e5fc4315b4a7814cd"' \
-X PUT \
-d '{
"artifacts_dir": "foobar",
"purge_settings":{
"purge_start_disk_space": 30,
"purge_upto_disk_space": 60
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#artifacts-config"
},
"self" : {
"href" : "http://ci.example.com/go/api/admin/config/server/artifact_config"
}
},
"artifacts_dir" : "foobar",
"purge_settings" : {
"purge_start_disk_space" : 30.0,
"purge_upto_disk_space" : 60.0
}
}
Available since v19.11.0.
HTTP Request
PUT /go/api/admin/config/server/artifact_config
Returns
Authorization Configuration
The Authorization configuration API allows admin users to manage authorization configuration. This config will later be used by a plugin to authorize a user in the GoCD server.
The authorization configuration object
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the authorization configuration. |
plugin_id |
String | The plugin identifier of the authorization plugin. |
allow_only_known_users_to_login |
String | Allow only those users to login who have explicitly been added by an administrator. |
properties |
Array | The list of configuration properties that represent the configuration of this authorization configuration. |
Get all authorization configurations
$ curl 'https://ci.example.com/go/api/admin/security/auth_configs' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs"
},
"doc": {
"href": "https://api.gocd.org/#authorization-configuration"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
}
},
"_embedded": {
"auth_configs": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
},
"doc": {
"href": "https://api.gocd.org/#authorization-configuration"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
}
},
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url"
}
]
}
]
}
}
Lists all available authorization configurations.
Updated to version v2 since v19.11.0.
Available since v17.5.0.
HTTP Request
GET /go/api/admin/security/auth_configs
Returns
An array of authorization configurations object.
Get an authorization configuration
$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
},
"doc": {
"href": "https://api.gocd.org/#authorization-configuration"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
}
},
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url:389"
},
{
"key": "SearchBase",
"value": "ou=users,ou=system"
},
{
"key": "ManagerDN",
"value": "uid=admin,ou=system"
},
{
"key": "SearchFilter",
"value": "uid"
},
{
"key": "Password",
"encrypted_value": "GLzARJ+Qr+M="
},
{
"key": "DisplayNameAttribute",
"value": "displayName"
},
{
"key": "EmailAttribute",
"value": "mail"
}
]
}
Gets authorization configuration for specified id.
Updated to version v2 since v19.11.0.
Available since v17.5.0.
HTTP Request
GET /go/api/admin/security/auth_configs/:auth_config_id
Returns
The authorization configuration object.
Create an authorization configuration
$ curl 'https://ci.example.com/go/api/admin/security/auth_configs' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url:389"
},
...
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
},
"doc": {
"href": "https://api.gocd.org/#authorization-configuration"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
}
},
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url:389"
},
{
"key": "SearchBase",
"value": "ou=users,ou=system"
},
{
"key": "ManagerDN",
"value": "uid=admin,ou=system"
},
{
"key": "SearchFilter",
"value": "uid"
},
{
"key": "Password",
"encrypted_value": "GLzARJ+Qr+M="
},
{
"key": "DisplayNameAttribute",
"value": "displayName"
},
{
"key": "EmailAttribute",
"value": "mail"
}
]
}
Creates an authorization configuration
Updated to version v2 since v19.11.0.
Available since v17.5.0.
HTTP Request
POST /go/api/admin/security/auth_configs
Returns
The authorization configuration object.
Update an authorization configuration
$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url:10389"
},
{
"key": "SearchBase",
"value": "ou=users,ou=system"
},
{
"key": "ManagerDN",
"value": "uid=admin,ou=system"
}
...
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/ldap"
},
"doc": {
"href": "https://api.gocd.org/#authorization-configuration"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/auth_configs/:auth_config_id"
}
},
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"allow_only_known_users_to_login": false,
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url:10389"
},
{
"key": "SearchBase",
"value": "ou=users,ou=system"
},
{
"key": "ManagerDN",
"value": "uid=admin,ou=system"
},
{
"key": "SearchFilter",
"value": "uid"
},
{
"key": "Password",
"encrypted_value": "GLzARJ+Qr+M="
},
{
"key": "DisplayNameAttribute",
"value": "displayName"
},
{
"key": "EmailAttribute",
"value": "mail"
}
]
}
Update some attributes of an authorization configuration.
Updated to version v2 since v19.11.0.
Available since v17.5.0.
HTTP Request
PUT /go/api/admin/security/auth_configs/:auth_config_id
Returns
The updated authorization configuration object.
Delete an authorization configuration
$ curl 'https://ci.example.com/go/api/admin/security/auth_configs/ldap' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"message": "The security auth config 'ldap' was deleted successfully."
}
Deletes the authorization configuration.
Updated to version v2 since v19.11.0.
Available since v17.5.0.
HTTP Request
DELETE /go/api/admin/security/auth_configs/:auth_config_id
Returns
A message if the authorization configuration is deleted or not.
Backup Config
The Backup Config API allows users to configure backup settings for the GoCD server.
The Backup Config Object
Available since v19.6.0.
| Attribute | Type | Description |
|---|---|---|
schedule |
String | The backup schedule. See the quartz documentation for syntax and examples. |
post_backup_script |
String | The script that will be executed once the backup finishes. See the gocd documentation for details. |
email_on_failure |
Boolean | If set to true, an email will be sent when backup fails. |
email_on_success |
Boolean | If set to true, an email will be sent when backup completes successfully. |
Get Backup Config
$ curl 'https://ci.example.com/go/api/config/backup' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/config/backup"
},
"doc": {
"href": "https://api.gocd.org/#backup-config"
}
},
"email_on_failure" : false,
"email_on_success" : false,
"post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
"schedule" : "0 0 2 * * ?"
}
Available since v19.6.0.
HTTP Request
GET /go/api/config/backup
Returns
Create or Update Backup Config
$ curl 'https://ci.example.com/go/api/config/backup' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"email_on_failure" : false,
"email_on_success" : false,
"post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
"schedule" : "0 0 2 * * ?"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/config/backup"
},
"doc": {
"href": "https://api.gocd.org/#backup-config"
}
},
"email_on_failure" : false,
"email_on_success" : false,
"post_backup_script" : "/usr/local/bin/copy-gocd-backup-to-s3",
"schedule" : "0 0 2 * * ?"
}
Available since v19.6.0.
HTTP Request
POST /go/api/config/backup
PUT /go/api/config/backup
Returns
Delete Backup Config
$ curl 'https://ci.example.com/go/api/config/backup' </span>
-u 'username:password' </span>
-H 'Accept: application/vnd.go.cd.v1+json' </span>
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Backup config was deleted successfully!"
}
Available since v19.6.0.
HTTP Request
DELETE /go/api/config/backup
Returns
A message confirmation if the backup config was deleted.
Cluster Profiles
The cluster profiles API allows users with admin authorization to manage cluster profiles.
The cluster profile object
Available since v19.3.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the cluster profile. |
plugin_id |
String | The plugin identifier of the cluster profile. |
properties |
Array | The list of configuration properties that represent the configuration of this profile. |
Get all cluster profiles
$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles"
},
"doc": {
"href": "https://api.gocd.org/#cluster-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
}
},
"_embedded": {
"profiles": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
},
"doc": {
"href": "https://api.gocd.org/#cluster-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
}
},
"id": "prod-cluster",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}
]
}
}
Lists all available cluster profiles.
Available since v19.3.0.
HTTP Request
GET /go/api/admin/elastic/cluster_profiles
Returns
An array of cluster profiles.
Get a cluster profile
$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
},
"doc": {
"href": "https://api.gocd.org/#cluster-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
}
},
"id": "prod-cluster",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}
Gets cluster profile config for specified profile id.
Available since v19.3.0.
HTTP Request
GET /go/api/admin/elastic/cluster_profiles/:id
Returns
Create a cluster profile
$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "prod-cluster",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
},
"doc": {
"href": "https://api.gocd.org/#cluster-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
}
},
"id": "prod-cluster",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}
Creates a cluster profile
Available since v19.3.0.
HTTP Request
POST /go/api/admin/elastic/cluster_profiles
Returns
Update a cluster profile
$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster"
},
"doc": {
"href": "https://api.gocd.org/#cluster-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/elastic/cluster_profiles/:id"
}
},
"id": "prod-cluster",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"properties": [
{
"key": "GoServerUrl",
"value": "https://ci.example.com/go"
}
]
}
Update some attributes of a cluster profile.
Available since v19.3.0.
HTTP Request
PUT /go/api/admin/elastic/cluster_profiles/:id
Returns
The updated cluster profile object.
Delete a cluster profile
$ curl 'https://ci.example.com/go/api/admin/elastic/cluster_profiles/prod-cluster' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message": "Cluster profile 'prod-cluster' was deleted successfully."
}
Deletes the cluster profile.
Available since v19.3.0.
HTTP Request
DELETE /go/api/admin/elastic/cluster_profiles/:id
Returns
A message if the cluster profile is deleted or not.
Config Repo
The config repo API allows admin users to define and manage config repos using which pipelines defined in external repositories can be included in GoCD, thereby allowing users to have their Pipeline as code.
The config repo object
Available since v17.12.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | Each config repo is associated with an unique id by which it can be referenced. Id is mandatory field for config repo. |
plugin_id |
String | The name of the config repo plugin. |
material |
Object | The material to be used by the config repo. |
configuration |
Object | The list of properties (key-value pairs) to be provided for using the plugin. |
rules |
Array | The list of rules, which allows restricting the entities that the config repo can refer to. Referring to the GoCD entities is denied by default, an explicit rule should be added to allow a specific resource to allow the config repo to refer it. Since v20.2.0. |
The config repo definition object
Available since v20.1.0.
| Attribute | Type | Description |
|---|---|---|
environments |
Array | The list of environments defined in config repository. |
groups |
Array | The list of pipeline groups defined in config repository. |
The config repo environment definition object
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of an environment. |
The config repo pipeline groups definition object
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of a pipeline group. |
pipelines |
Array | The list of pipeline information defined in config repository. |
The config repo pipeline definition object
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of a pipeline. |
The config repo rule object
| Attribute | Type | Description |
|---|---|---|
directive |
String | The type of rule which can be either allow or deny. |
action |
String | The action that is being controlled via this rule. Only refer is supported as of now. |
type |
String | The type of entity that the rule is applied on. Currently environment, pipeline and pipeline_group are supported. |
resource |
String | The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities. |
The configuration property object
{
"configuration": [
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "1f3rrs9uhn63hd"
},
{
"key": "url",
"value": "https://github.com/sample/example.git",
"is_secure": true
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | The name of the property key. |
value |
String | The value of the property. You MUST specify one of value or encrypted_value. |
encrypted_value |
String | The encrypted value of the property. You MUST specify one of value or encrypted_value. |
is_secure |
Boolean | Specify whether the given property is secure or not. If true and encrypted_value is not specified, GoCD will store the value in encrypted format. |
The config repository material object
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a material. Can be one of git, svn, hg, p4, tfs. |
attributes |
Object | The attributes for each material type. |
The git material attributes
{
"type": "git",
"attributes": {
"url": "https://github.com/gocd/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the git repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
encrypted_password |
String | The encrypted password for the specified user. Since v19.4.0. |
branch |
String | The git branch to build. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The svn material attributes
{
"type": "svn",
"attributes": {
"url": "svn://svn.example.com/myProject/trunk",
"username": "admin",
"auto_update": true,
"encrypted_password": "aSdiFgRRZ6A=",
"check_externals": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the subversion repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
auto_update |
Boolean | Whether to poll for new changes or not. |
check_externals |
Boolean | Whether the changes o the externals will trigger the pipeline automatically or not. |
The mercurial material attributes
{
"type": "hg",
"attributes": {
"url": "http://hg.example.com/hg/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "feature",
"auto_update": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the mercurial repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
encrypted_password |
String | The encrypted password for the specified user. Since v19.4.0. |
branch |
String | The mercurial branch to build. Since v19.4.0. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The perforce material attributes
{
"type": "p4",
"attributes": {
"port": "p4.example.com:8080",
"use_tickets": true,
"view": "sample_view",
"auto_update": true,
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A="
}
}
| Attribute | Type | Description |
|---|---|---|
port |
String | Perforce server connection to use ([transport:]host:port). |
use_tickets |
Boolean | Whether to work with the Perforce tickets or not. |
view |
String | The Perforce view. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username to be used. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
The tfs material attributes
{
"type": "tfs",
"attributes": {
"url": "http://tfs.exampe.com:8000/tfs",
"project_path": "$/",
"domain": "corporate/domain",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A="
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL for the Collection on the TFS Server. |
project_path |
String | The project path within the TFS collection. |
domain |
String | The domain name for TFS authentication credentials. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username of the account to access the TFS collection. |
password |
String | The password of the account to access the TFS collection. |
encrypted_password |
String | The encrypted password of the account to access the TFS collection. |
Get all Config repos
$ curl 'https://ci.example.com/go/api/admin/config_repos' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos"
}
},
"_embedded": {
"config_repos": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/repo1"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
},
"id": "repo1",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
},
"configuration": [
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "pipeline_group",
"resource": "*"
}
]
}
]
}
}
Lists all available config repos, these are config repositories that are present in the in cruise-config.xml.
Updated to version v4 since v20.8.0.
Available since v17.12.0.
HTTP Request
GET /go/api/admin/config_repos
Returns
A list of config-repo objects
Get a Config repo
$ curl 'https://ci.example.com/go/api/admin/config_repos/repo1' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/repo1"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
},
"id": "repo1",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
},
"configuration": [
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "pipeline_group",
"resource": "*"
}
]
}
Gets the config repo object for a specified id.
Updated to version v4 since v20.8.0.
Available since v17.12.0.
HTTP Request
GET /go/api/admin/config_repos/:id
Returns
A config-repo object
Create a Config repo
$ curl 'http://ci.example.com/go/api/admin/config_repos' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json' \
-H 'Content-Type:application/json' \
-X POST -d '{
"id": "repo-2",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example2.git",
"username": "bob",
"password": "pass",
"branch": "master",
"auto_update": true
}
},
"configuration": [
{
"key": "pattern",
"value": "*.myextension"
}
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "pipeline_group",
"resource": "*"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/repo-2"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
},
"id": "repo-2",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example2.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
},
"configuration": [
{
"key": "pattern",
"value": "*.myextension"
}
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "pipeline_group",
"resource": "*"
}
]
}
Create a config repo object.
Updated to version v4 since v20.8.0.
Available since v17.12.0.
HTTP Request
POST /go/api/admin/config_repos
Returns
A new config-repo object
Note: since version 18.12.0, it is not possible anymore to provide a material name as redundant with the id.
Update Config repo
$ curl 'https://ci.example.com/go/api/admin/config_repos/repo-1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
-X PUT \
-d '{
"id": "repo-1",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example2.git",
"username": "bob",
"password": "pass",
"branch": "master",
"auto_update": true
}
},
"configuration": [
{
"key": "pattern",
"value": "*.myextension"
}
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "environment",
"resource": "*"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/repo-2"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
},
"id": "repo-2",
"plugin_id": "json.config.plugin",
"material": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/gocd-json-config-example2.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
},
"configuration": [
{
"key": "pattern",
"value": "*.myextension"
}
],
"rules": [
{
"directive": "allow",
"action": "refer",
"type": "environment",
"resource": "*"
}
]
}
Update config repos for specified config repo id.
Updated to version v4 since v20.8.0.
Available since v17.12.0.
HTTP Request
PUT /go/api/admin/config_repos/:id
Returns
The updated config-repo object
Delete a Config repo
$ curl 'https://ci.example.com/go/api/admin/config_repos/repo-1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"message": "The config repo 'repo-1' was deleted successfully."
}
Deletes the config repo.
Updated to version v4 since v20.8.0.
Available since v17.12.0.
HTTP Request
DELETE /go/api/admin/config_repos/:id
Returns
A message whether the config repo is deleted or not.
Export pipeline config to config repo format
$ curl 'http://ci.example.com/go/api/admin/export/pipelines/pip1?plugin_id=yaml.config.plugin' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
The above command returns YML structured like this:
HTTP/1.1 200 OK
Content-Type: application/x-yaml; charset=utf-8
ETag: "92d3496403f7a3240fc0ba8895c5abfef24a72255360ebf1c04b4eb304a63eaa"
Content-Disposition: attachment; filename="pip1.gocd.yaml"
format_version: 3
pipelines:
pip1:
group: second
label_template: ${COUNT}
lock_behavior: none
materials:
git:
git: foo
shallow_clone: false
auto_update: true
branch: master
stages:
- defaultStage:
fetch_materials: true
keep_artifacts: false
clean_workspace: false
approval:
type: success
jobs:
defaultJob:
timeout: 0
tasks:
- nant:
run_if: passed
Exports pipeline configurations into a format consumable by the specified config repo plugin.
Available since v19.1.0.
HTTP Request
GET /go/api/admin/export/pipelines/:pipeline_name
Returns
The format and contents of the response as well as the Content-Type are determined by the specified config repo plugin.
Preflight check of config repo configurations
$ curl "https://ci.example.com/go/api/admin/config_repo_ops/preflight?pluginId=yaml.config.plugin&repoId=myExistingRepo" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-F 'files[]=@path/to/file1.gocd.yaml' \
-F 'files[]=@path/to/file2.gocd.yaml'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"errors" : [ ],
"valid" : true
}
Checks posted definition file(s) for syntax and merge errors without updating the current GoCD configuration.
Available since v19.2.0.
HTTP Request
When validating definitions before the corresponding config repo configuration has been added to GoCD, do not supply a repoId parameter:
POST /go/api/admin/config_repo_ops/preflight?pluginId=:plugin_id
When validating definition updates to an existing config repo configuration, the repoId parameter is required:
POST /go/api/admin/config_repo_ops/preflight?pluginId=:plugin_id&repoId=:config_repo_id
Returns
A boolean indicating whether the content can be successfully merged and array of errors (if content isn’t mergeable).
Trigger update of config repository
$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/trigger_update" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json' \
-H 'X-GoCD-Confirm: true'\
-X POST
The above command returns JSON structured like this:
HTTP/1.1 201 Created
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"message": "OK"
}
Triggers the update for config repository to get latest revisions.
Updated to version v4 since v20.8.0.
Available since v20.2.0.
HTTP Request
POST /go/api/admin/config_repos/:config_repo_id/trigger_update
Returns
one of -
- “OK” message indicating that update for config repository is scheduled.
- “Update already in progress.” message with status code
409indicating update is already in progress
Status of config repository update
$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/status" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"in_progress": false
}
Get the status of config repository update operation.
Updated to version v4 since v20.8.0.
Available since v20.2.0.
HTTP Request
GET /go/api/admin/config_repos/:config_repo_id/status
Returns
Boolean which indicates that the update of config repository is in progress or not.
Definitions defined in config repo
$ curl "https://ci.example.com/go/api/admin/config_repos/config_repo_id/definitions" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"environments": [{
"name": "dev"
}],
"groups": [{
"name": "config-repo-group",
"pipelines": [{
"name": "up43"
}]
}]
}
Get the entities defined in config repository.
Updated to version v4 since v20.8.0.
Available since v20.2.0.
HTTP Request
GET /go/api/admin/config_repos/:config_repo_id/definitions
Returns
The config repository definition object
Configuration Repository
This endpoint allows you to clone and fetch a copy of the configuration repository.
Clone the configuration repository
git clone 'https://username:password@ci.example.com/go/api/config-repository.git'
Available since v16.6.0.
Default Job Timeout
The job timeout API allows to set default timeout value for hung jobs.
The Job Timeout Config Object
Available since v19.11.0.
| Attribute | Type | Description |
|---|---|---|
default_job_timeout |
String | This entry will be used as the default timeout value in minutes for hung jobs. A job is considered as hung if it does not generate any console output for default_job_timeout minutes. |
Get JobTimeout Config
$ curl 'https://ci.example.com/go/api/admin/config/server/default_job_timeout' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#default-job-timeout"
},
"self" : {
"href" : "http://ci.example.com/go/api/admin/config/server/default_job_timeout"
}
},
"default_job_timeout" : "0"
}
Available since v19.11.0.
HTTP Request
GET /go/api/admin/config/server/default_job_timeout
Returns
Update job Timeout Config
$ curl 'https://ci.example.com/go/api/admin/config/server/default_job_timeout' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"default_job_timeout" : "10"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#default-job-timeout"
},
"self" : {
"href" : "http://localhost:8153/go/api/admin/config/server/default_job_timeout"
}
},
"default_job_timeout" : "10"
}
Available since v19.11.0.
HTTP Request
POST /go/api/admin/config/server/default_job_timeout
PUT /go/api/admin/config/server/default_job_timeout
Returns
Elastic Agent Profiles
The elastic agent profile API allows users with admin and group admin authorization to manage profiles that allow creation elastic agents.
The elastic agent profile object
Available since v19.3.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the elastic agent profile. |
cluster_profile_id |
String | The identifier of the cluster profile to which current elastic agent profile belongs. |
properties |
Array | The list of configuration properties that represent the configuration of this profile. |
Get all elastic agent profiles
$ curl 'https://ci.example.com/go/api/elastic/profiles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/elastic/profiles"
},
"doc": {
"href": "https://api.gocd.org/#elastic-agent-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
}
},
"_embedded": {
"profiles": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
},
"doc": {
"href": "https://api.gocd.org/#elastic-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
}
},
"id": "unit-tests",
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "alpine:latest"
},
{
"key": "Command",
"value": ""
},
{
"key": "Environment",
"value": ""
},
{
"key": "MaxMemory",
"value": "200M"
},
{
"key": "ReservedMemory",
"value": "150M"
}
]
}
]
}
}
Lists all available elastic agent profiles.
Available since v19.3.0.
HTTP Request
GET /go/api/elastic/profiles
Returns
An array of elastic agent profiles.
Get an elastic agent profile
$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
},
"doc": {
"href": "https://api.gocd.org/#elastic-agent-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
}
},
"id": "unit-tests",
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "gocdcontrib/gocd-dev-build"
},
{
"key": "Environment",
"value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
}
]
}
Gets elastic agent profile config for specified profile.
Available since v19.3.0.
HTTP Request
GET /go/api/elastic/profiles/:profile_id
Returns
The elastic agent profile object.
Create an elastic agent profile
$ curl 'https://ci.example.com/go/api/elastic/profiles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "unit-tests",
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "gocdcontrib/gocd-dev-build"
},
{
"key": "Environment",
"value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
},
"doc": {
"href": "https://api.gocd.org/#elastic-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
}
},
"id": "unit-tests",
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "gocdcontrib/gocd-dev-build"
},
{
"key": "Environment",
"value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
}
]
}
Creates an elastic agent profile
Available since v19.3.0.
HTTP Request
POST /go/api/elastic/profiles
Returns
The elastic agent profile object.
Update an elastic agent profile
$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "gocdcontrib/gocd-dev-build:1.0.0"
},
{
"key": "Environment",
"value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/elastic/profiles/unit-tests"
},
"doc": {
"href": "https://api.gocd.org/#elastic-agent-profiles"
},
"find": {
"href": "https://ci.example.com/go/api/elastic/profiles/:profile_id"
}
},
"id": "unit-tests",
"cluster_profile_id": "prod-cluster",
"properties": [
{
"key": "Image",
"value": "gocdcontrib/gocd-dev-build:1.0.0"
},
{
"key": "Environment",
"value": "JAVA_HOME=/opt/java\nMAKE_OPTS=-j8"
}
]
}
Update some attributes of an elastic agent profile.
Available since v19.3.0.
HTTP Request
PUT /go/api/elastic/profiles/:profile_id
Returns
The updated elastic agent profile object.
Delete an elastic agent profile
$ curl 'https://ci.example.com/go/api/elastic/profiles/unit-tests' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"message": "Elastic agent profile 'unit-test' was deleted successfully."
}
Deletes the profile.
Available since v19.3.0.
HTTP Request
DELETE /go/api/elastic/profiles/:profile_id
Returns
A message if the elastic agent profile is deleted or not.
Environment Config
The environment config API allows users with administrator role to manage environment config.
The environment config object
Available since v16.7.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of environment. |
pipelines |
Array | List of pipeline names that should be added to this environment. |
environment_variables |
Array | The list of environment variables that will be passed to all tasks (commands) that are part of this environment. |
Get all environments
$ curl 'https://ci.example.com/go/api/admin/environments' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
}
},
"_embedded": {
"environments": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments/foobar"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/environments/:environment_name"
}
},
"name": "foobar",
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
]
}
}
Lists all available environments.
Updated to version v3 since v19.9.0.
Available since v16.7.0.
HTTP Request
GET /go/api/admin/environments
Returns
An array of environment config objects.
Get environment config
$ curl 'https://ci.example.com/go/api/admin/environments/my_environment' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments/my_environment"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/environments/:environment_name"
}
},
"name": "my_environment",
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
Gets environment config for specified environment name.
Updated to version v3 since v19.9.0.
Available since v16.7.0.
HTTP Request
GET /go/api/admin/environments/:environment_name
Returns
The environment config object.
Create an environment
$ curl 'https://ci.example.com/go/api/admin/environments' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name" : "new_environment",
"pipelines" : [
{
"name" : "up2"
}
],
"environment_variables" : [
{
"name" : "username",
"value" : "admin",
"secure" : false
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "d3b07384d113edec49eaa6238ad5ff00"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments/new_environment"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/environments/:environment_name"
}
},
"name": "new_environment",
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
Creates an environment
Updated to version v3 since v19.9.0.
Available since v16.7.0.
HTTP Request
POST /go/api/admin/environments
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
name |
String | The environment config name. |
pipelines |
Array | The list of pipeline names that belongs to the specified environment. |
environment_variables |
Array | The list of environment variables that will be passed to all tasks (commands) that are part of this environment. |
Returns
Update an environment
$ curl 'https://ci.example.com/go/api/admin/environments/new_environment' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "26b227605daf6f2d7768c8edaf61b861"' \
-X PUT \
-d '{
"name" : "new_environment",
"pipelines" : [ { "name" : "pipeline1" } ]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments/new_environment"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/environments/:environment_name"
}
},
"name": "new_environment",
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/pipeline1"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42"
}
],
"environment_variables": [
]
}
Update some attributes of an environment.
Updated to version v3 since v19.9.0.
Available since v16.7.0.
HTTP Request
PUT /go/api/admin/environments/:environment_name
All of the following properties must be specified. Not specifying a property will either fail the request or make that value blank during the update.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of environment. |
pipelines |
Array | List of pipeline names that should be part of this environment. |
environment_variables |
Array | The list of environment variables that will be passed to all tasks (commands) that are part of this environment. |
Returns
The updated environment config object.
Patch an environment
$ curl 'https://ci.example.com/go/api/admin/environments/new_environment' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"pipelines": {
"add": ["up42"],
"remove": ["sample"]
},
"environment_variables": {
"add": [
{
"name": "GO_SERVER_URL",
"value": "https://ci.example.com/go"
}
],
"remove": ["URL"]
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/environments/new_environment"
},
"doc": {
"href": "https://api.gocd.org/#environment-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/environments/:environment_name"
}
},
"name": "new_environment",
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/pipeline1"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42"
}
],
"environment_variables": [
{
"name": "GO_SERVER_URL",
"value": "https://ci.example.com/go",
"secure": false
}
]
}
Update some attributes of an environment.
Updated to version v3 since v19.9.0.
Available since v16.10.0.
HTTP Request
PATCH /go/api/admin/environments/:environment_name
At least one of the following properties must be specified, not specifying the property will leave it unchanged.
The environments patch operation attributes
{
"pipelines": {
"add": [
"Dev",
"Test"
],
"remove": [
"Production"
]
},
"environment_variables": {
"add": [
{
"name": "GO_SERVER_URL",
"value": "https://ci.example.com/go"
}
],
"remove": [
"URL"
]
}
}
| Attribute | Type | Description |
|---|---|---|
pipelines |
Object | The pipelines update operation to be performed on the set of pipelines. |
environment_variables |
Object | The environment variables update operation to be performed on the set of environment variables. |
The environments pipeline-update operation attributes
{
"add": [
"Dev",
"Test"
],
"remove": [
"Production"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of pipelines which needs to be added to the specified environment. |
remove |
Array | The list of pipelines which needs to be removed to the specified environment. |
The environments environment-variable-update operation attributes
{
"add": [
{
"name": "USERNAME",
"value": "go-user"
},
{
"name": "PASSWORD",
"encrypted_value": "1f3rrs9uhn63hd",
"secure": true
}
],
"remove": [
"URL"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of environment variables which needs to be added to the specified environment. |
remove |
Array | The list of environment variable names which needs to be removed to the specified environment. |
Returns
The updated environment config object.
Delete an environment
$ curl 'https://ci.example.com/go/api/admin/environments/my_environment' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "Environment 'my_environment' was deleted successfully."
}
Deletes an environment.
Updated to version v3 since v19.9.0.
Available since v16.7.0.
HTTP Request
DELETE /go/api/admin/environments/:environment_name
Returns
A message confirmation if the environment was deleted.
GoCD-level Configuration
The configuration API allows users with administration role to view and manage configuration.
Get configuration
$ curl 'https://ci.example.com/go/api/admin/config.xml' \
-u 'username:password'
The above command returns the contents of the config file
HTTP/1.1 200 OK
X-CRUISE-CONFIG-MD5: c21b6c9f1b24a816cddf457548a987a9
Content-Type: text/xml
<?xml version="1.0" encoding="utf-8"?>
<cruise
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="cruise-config.xsd"
schemaVersion="75">
<server serverId="9C0C0282-A554-457D-A0F8-9CF8A754B4AB">
<security>
<passwordFile path="/etc/go/password.properties" />
</security>
</server>
<pipelines group="defaultGroup" />
</cruise>
Gets the current configuration file.
Available since v14.3.0.
HTTP Request
GET /go/api/admin/config.xml
Other convenience APIs
GET /go/api/admin/config/current.xml
or
GET /go/api/admin/config/:md5.xml
Returns
The contents of the configuration file.
Mailserver Config
The mailserver config API allows admins to setup the SMTP server configuration, so GoCD can send emails.
The Mailserver Config Object
Available since v19.8.0.
| Attribute | Type | Description |
|---|---|---|
hostname |
String | The SMTP server hostname (or IP address). |
port |
Integer | The SMTP server port. |
username |
String | The username required to authenticate with the SMTP server. |
password |
String | The password required to authenticate with the SMTP server. |
encrypted_password |
String | The encrypted password required to authenticate with the SMTP server. |
tls |
Boolean | Whether the SMTP server connection should should use SSL/TLS. |
sender_email |
Boolean | The email address of the sender. All emails sent by the GoCD server will use this email address in the Form field. |
admin_email |
Boolean | The email address of the server administrator. Any emails that require attention from adminstrators will be sent to this email address. |
Get Mailserver Config
$ curl 'https://ci.example.com/go/api/config/mailserver' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/config/mailserver"
},
"doc": {
"href": "https://api.gocd.org/#mailserver-config"
}
},
"hostname" : "smtp.example.com",
"port" : 465,
"username" : "user@example.com",
"encrypted_password" : "AES:lzcCuNSe4vUx+CsWgN11Uw==:Q2OlnqIf9S++yMPqSCx8qg==",
"tls" : true,
"sender_email" : "no-reply@example.com",
"admin_email" : "gocd-admins@example.com"
}
Available since v19.8.0.
HTTP Request
GET /go/api/config/mailserver
Returns
Create or Update Mailserver Config
$ curl 'https://ci.example.com/go/api/config/mailserver' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"hostname" : "smtp.example.com",
"port" : 465,
"username" : "user@example.com",
"password" : "p@ssw0rd",
"tls" : true,
"sender_email" : "no-reply@example.com",
"admin_email" : "gocd-admins@example.com"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/config/mailserver"
},
"doc": {
"href": "https://api.gocd.org/#mailserver-config"
}
},
"hostname" : "smtp.example.com",
"port" : 465,
"username" : "user@example.com",
"encrypted_password" : "AES:lzcCuNSe4vUx+CsWgN11Uw==:Q2OlnqIf9S++yMPqSCx8qg==",
"tls" : true,
"sender_email" : "no-reply@example.com",
"admin_email" : "gocd-admins@example.com"
}
Available since v19.8.0.
HTTP Request
POST /go/api/config/mailserver
PUT /go/api/config/mailserver
Returns
Delete Mailserver Config
$ curl 'https://ci.example.com/go/api/config/mailserver' </span>
-u 'username:password' </span>
-H 'Accept: application/vnd.go.cd.v1+json' </span>
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Mailserver config was deleted successfully!"
}
Available since v19.8.0.
HTTP Request
DELETE /go/api/config/mailserver
Returns
A message confirmation if the mailserver config was deleted.
Materials
The materials API allows users to query materials in the GoCD configuration.
The material object
Available since v19.6.0.
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a material. Can be one of git, hg, svn, p4, tfs, dependency, package, plugin. |
fingerprint |
String | The fingerprint of the material. |
attributes |
Object | The attributes for each material type. |
The git material attributes
{
"type": "git",
"attributes": {
"url": "https://github.com/gocd/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the git repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
branch |
String | The git branch to build. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The svn material attributes
{
"type": "svn",
"attributes": {
"url": "svn://svn.example.com/myProject/trunk",
"username": "admin",
"auto_update": true,
"encrypted_password": "aSdiFgRRZ6A=",
"check_externals": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the subversion repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
auto_update |
Boolean | Whether to poll for new changes or not. |
check_externals |
Boolean | Whether the changes o the externals will trigger the pipeline automatically or not. |
The mercurial material attributes
{
"type": "hg",
"attributes": {
"url": "http://hg.example.com/hg/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "feature",
"auto_update": true
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the mercurial repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
branch |
String | The mercurial branch to build. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The perforce material attributes
{
"type": "p4",
"attributes": {
"port": "p4.example.com:8080",
"use_tickets": true,
"view": "sample_view",
"auto_update": true,
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A="
}
}
| Attribute | Type | Description |
|---|---|---|
port |
String | Perforce server connection to use ([transport:]host:port). |
use_tickets |
Boolean | Whether to work with the Perforce tickets or not. |
view |
String | The Perforce view. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username to be used. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
The tfs material attributes
{
"type": "tfs",
"attributes": {
"url": "http://tfs.exampe.com:8000/tfs",
"project_path": "$/",
"domain": "corporate/domain",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A="
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL for the Collection on the TFS Server. |
project_path |
String | The project path within the TFS collection. |
domain |
String | The domain name for TFS authentication credentials. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username of the account to access the TFS collection. |
password |
String | The password of the account to access the TFS collection. |
encrypted_password |
String | The encrypted password of the account to access the TFS collection. |
The package material attributes
{
"type": "package",
"attributes": {
"ref": "e289f497-057b-46bc-bb69-8043454f5c1b"
}
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique package repository id. |
The dependency material attributes
{
"materials": [
{
"type": "dependency",
"attributes": {
"name": "dependency",
"pipeline": "upstream",
"stage": "upstream_stage",
"auto_update": true,
"ignore_for_scheduling": false
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
pipeline |
String | The name of a pipeline that this pipeline depends on. |
stage |
String | The name of a stage which will trigger this pipeline once it is successful. |
auto_update |
Boolean | Whether to poll for new changes or not. |
ignore_for_scheduling |
Boolean | Whether the pipeline should be triggered when there are changes in this material. Since v19.10.0. |
The plugin material attributes
{
"materials": [
{
"type": "plugin",
"attributes": {
"ref": "5e3612f7-6aa1-4d75-a9b7-6aeb52d98012",
"filter": null,
"invert_filter": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique scm plugin repository id. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. |
The filter object
{
"filter": {
"ignore": [
"README.md",
"docs/**.html"
]
}
}
| Attribute | Type | Description |
|---|---|---|
ignore |
String | The pattern for the files to be ignored. |
Get all materials
$ curl 'https://ci.example.com/go/api/config/materials' \
-u 'username:password'
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#materials"
},
"self": {
"href": "https://ci.example.com/go/api/config/materials"
}
},
"_embedded": {
"materials": [
{
"type": "git",
"fingerprint": "458ce82419bdbe41a4007ad713a730e5e467ed4fbefb421bf58aeff3e9c36e4b",
"attributes": {
"url": "https://github.com/gocd/gocd",
"destination": null,
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": false,
"branch": "master",
"submodule_folder": null,
"shallow_clone": false
}
},
{
"type": "svn",
"fingerprint": "6b0cd6b9181434866c555f3c3bb780e950389a456764c876d804c848efbad554",
"attributes": {
"url": "https://github.com/gocd/gocd",
"destination": "test",
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": false,
"username": "admin",
"encrypted_password": "AES:lTFKwi5NvrlqmQ3LOQ5UQA==:Ebggz5N27w54NrhSXKIbng==",
"check_externals": false
}
},
{
"type": "hg",
"fingerprint": "f6b61bc6b33e524c2a94c5be4a4661e5f1d2b74ca089418de20de10b282e39e9",
"attributes": {
"url": "ssh://hg@bitbucket.org/example/gocd-hg",
"destination": "test",
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": false,
"branch": ""
}
},
{
"type": "dependency",
"fingerprint": "21f7963a8eca6cced5b4f20b57b4e9cb8edaed29d683c83621a77dfb499c553d",
"attributes": {
"pipeline": "up42",
"stage": "up42_stage",
"name": "up42_material",
"auto_update": true,
"ignore_for_scheduling": false
}
}
]
}
}
Lists all available materials, these are materials that are present in the cruise-config.xml or Config Repos.
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
GET /go/api/config/materials
Returns
An array of material objects.
Get material modifications
$ curl 'https://ci.example.com/go/api/materials/03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1/modifications' \
-u 'username:password'
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/materials/03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1/modifications"
},
"doc": {
"href": "https://api.gocd.org/#materials"
},
"find": {
"href": "https://ci.example.com/go/api/materials/:fingerprint/modifications/{offset}"
}
},
"_embedded": {
"modifications": [
{
"email_address": null,
"id": 7225,
"modified_time": 1435728005000,
"user_name": "Pick E Reader <pick.e.reader@example.com>",
"comment": "my hola mundo changes",
"revision": "a788f1876e2e1f6e5a1e91006e75cd1d467a0edb"
}
],
"pagination": {
"offset": 0,
"total": 1070,
"page_size": 10
}
}
}
Get material modifications by fingerprint
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
GET /go/api/materials/:fingerprint/modifications
With pagination
GET /go/api/materials/:fingerprint/modifications[/:offset]
Returns
A list of modification objects.
Notification Filters
The notification filters API allows the authenticated user to manage their notification filters.
The API depends on the SMTP settings and without it, the API will fail with following message.
{
"message": "SMTP settings are currently not configured. Ask your administrator to configure SMTP settings."
}
The notification filter object
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
id |
Number | The internal ID of the notification filter. |
pipeline |
String | The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified. |
stage |
String | The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified. |
event |
String | The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified. |
match_commits |
Boolean | Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false). |
Show all notification filters
$ curl 'https://ci.example.com/go/api/notification_filters' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/notification_filters"
},
"doc" : {
"href" : "https://api.gocd.org/20.1.0/#notification-filters"
}
},
"_embedded" : {
"filters" : [
{
"id": 10,
"pipeline": "my_pipeline",
"stage": "[Any Stage]",
"event": "Breaks",
"match_commits": true
}
]
}
}
Lists all notification filters for the authenticated user.
Updated to version v2 since v20.1.0.
Available since v17.5.0.
HTTP Request
GET /go/api/notification_filters
Returns
An array of notification filter objects representing the current set the user’s notification filters.
Create a notification filter
$ curl 'https://ci.example.com/go/api/notification_filters' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"pipeline": "my_pipeline",
"stage": "my_stage",
"event": "Breaks",
"match_commits": true
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/notification_filters/1"
},
"doc" : {
"href" : "https://api.gocd.org/#notification-filters"
},
"find" : {
"href" : "https://ci.example.com/go/api/notification_filters/:id"
}
},
"id" : 1,
"pipeline" : "up42",
"stage" : "up42_stage",
"event" : "Fails",
"match_commits" : false
}
Creates a notification filter for the authenticated user.
Updated to version v2 since v20.1.0.
Available since v17.5.0.
HTTP Request
POST /go/api/notification_filters
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified. |
stage |
String | The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified. |
event |
String | The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified. |
match_commits |
Boolean | Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false). |
Returns
A newly created notification filter object for the user.
Get a notification filter
$ curl 'https://ci.example.com/go/api/notification_filters/1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/notification_filters/1"
},
"doc" : {
"href" : "https://api.gocd.org/#notification-filters"
},
"find" : {
"href" : "https://ci.example.com/go/api/notification_filters/:id"
}
},
"id" : 1,
"pipeline" : "up42",
"stage" : "up42_stage",
"event" : "Fails",
"match_commits" : false
}
Get a notification filter for the authenticated user.
Updated to version v2 since v20.1.0.
Available since v17.5.0.
HTTP Request
GET /go/api/notification_filters/:id
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified. |
stage |
String | The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified. |
event |
String | The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified. |
match_commits |
Boolean | Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false). |
Returns
A newly created notification filter object for the user.
Update a notification filter
curl 'https://ci.example.com/go/api/notification_filters/1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"pipeline": "up42",
"stage": "up42_stage",
"event": "All",
"match_commits": false
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/notification_filters/1"
},
"doc" : {
"href" : "https://api.gocd.org/20.1.0/#notification-filters"
},
"find" : {
"href" : "https://ci.example.com/go/api/notification_filters/:id"
}
},
"id" : 1,
"pipeline" : "up42",
"stage" : "up42_stage",
"event" : "All",
"match_commits" : false
}
Update a existing notification filter for the authenticated user.
Updated to version v2 since v20.1.0.
Available since v17.5.0.
HTTP Request
PATCH /go/api/notification_filters/:id
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | The name of the pipeline to get notification for. Can also be [Any Pipeline] to get notification for any pipeline. This attribute MUST be specified. |
stage |
String | The name of the stage to get notification for. Can also be [Any Stage] to get notification for any stage. This attribute MUST be specified. |
event |
String | The name of event to get notificaton for. Can be one of: All, Passes, Fails, Breaks, Fixed, Cancelled. This attribute MUST be specified. |
match_commits |
Boolean | Boolean indicating if the notification filter should match only the user’s commits (true) or all commits (false). |
Returns
An updated notification filter object for the user.
Delete a notification filter
$ curl 'https://ci.example.com/go/api/notification_filters/1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"message" : "Notification filter is successfully deleted!"
}
Deletes a notification filter for the authenticated user.
Updated to version v2 since v20.1.0.
Available since v17.5.0.
HTTP Request
DELETE /go/api/notification_filters/:id
Returns
A message if the notification filter is deleted or not.
Packages
The package definition API v2 allows users to view, create and update the packages’ configuration.
The package config object
Available since v16.12.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the package. |
id |
String | Each material is associated with an id by which it can be referenced in the pipelines. If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update. |
auto_update |
Boolean | Whether the material is set to poll for new changes. Defaults to true. |
package_repo |
Object | The package repo object provides the id and name of the repository to which the package belongs. |
configuration |
Object | The list of properties (key-value pairs) to be provided for using the plugin. |
The package repository object
{
"package_repo": {
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "package-repository"
}
}
| Attribute | Type | Description |
|---|---|---|
id |
String | The id of the package repository. |
name |
String | The name of the package repository. |
Get all packages
$ curl 'https://ci.example.com/go/api/admin/packages' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages"
},
"doc": {
"href": "https://api.gocd.org/#packages"
}
},
"_embedded": {
"packages": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "package",
"id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
"auto_update": true,
"package_repo": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "foo"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "bar"
}
]
},
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/c3e1d398-96c0-4edd-a577-9b5c769d449b"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "another_package",
"id": "c3e1d398-96c0-4edd-a577-9b5c769d449b",
"auto_update": true,
"package_repo": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "npm"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "group"
},
{
"key": "VERSION_SPEC",
"value": "1"
},
{
"key": "ARCHITECTURE",
"value": "jar"
}
]
}
]
}
}
Lists all available packages, these are materials that are present in the in cruise-config.xml.
Updated to version v2 since v20.3.0.
Available since v16.12.0.
HTTP Request
GET /go/api/admin/packages
Returns
A list of packages.
Get a Package Material
$ curl 'https://ci.example.com/go/api/admin/packages/package.id' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v2+json'
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "08ae92bf39fc33e9d7326feb97047417"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/package.id"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "package",
"id": "package.id",
"auto_update": true,
"package_repo": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "foo"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "package_name"
}
]
}
Gets the package config for a specified package id.
Updated to version v2 since v20.3.0.
Available since v16.12.0.
HTTP Request
GET /go/api/admin/packages/:package_id
Returns
A package object.
Create a Package
$ curl "https://ci.example.com/go/api/admin/packages" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "package-id",
"name": "package_name",
"auto_update": false,
"package_repo": {
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "package"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/package-id"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "package_name",
"id": "package-id",
"auto_update": false,
"package_repo": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "foo"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "package"
}
]
}
Creates a package with specified configurations.
Updated to version v2 since v20.3.0.
Available since v16.12.0.
HTTP Request
POST /go/api/admin/packages
Returns
A new package object.
Edit a package
$ curl "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "08ae92bf39fc33e9d7326feb97047417"' \
-X PUT -d '{
"id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
"name": "foo",
"auto_update": true,
"package_repo": {
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"configuration": [{
"key": "PACKAGE_NAME",
"value": "update"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/f579bb13-bed3-4ad1-a547-ff9d9bcf56d4"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "foo",
"id": "f579bb13-bed3-4ad1-a547-ff9d9bcf56d4",
"auto_update": true,
"package_repo": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/273b246e-145d-49d2-a1a4-f0285af9cccc"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"id": "273b246e-145d-49d2-a1a4-f0285af9cccc",
"name": "foo"
},
"configuration": [
{
"key": "PACKAGE_NAME",
"value": "update"
}
]
}
Updates global package configuration for the specified package id.
Updated to version v2 since v20.3.0.
Available since v16.12.0.
HTTP Request
PUT /go/api/admin/packages/:package_id
Returns
The updated package object.
Delete a package material
$ curl 'https://ci.example.com/go/api/admin/packages/package-id' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"message": "The package definition 'package-id' was deleted successfully."
}
Deletes a package from the respective repository if it is not associated with any pipeline.
Available since v16.12.0.
HTTP Request
DELETE /go/api/admin/packages/:package_id
Returns
A message confirmation if the package was deleted.
Usages of the package
$ curl 'https://ci.example.com/go/api/admin/packages/package-id/usages' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links": {
"self": {
"href": "http://test.host/go/api/admin/packages/package-id/usages"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "http://test.host/go/api/admin/packages/:package_id/usages"
}
},
"usages" : [
{
"group" : "grp1",
"pipeline" : "pipeline1"
}
]
}
Gets the list of pipelines and group which uses the said package as a material
Updated to version v2 since v20.3.0.
HTTP Request
GET /go/api/admin/packages/:package_id/usages
Returns
A list of the usage object.
The usage object
{
"pipeline": "pipeline_name",
"group": "grp_name"
}
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | The name of the pipeline which uses the package as a material. |
group |
String | The group which the pipeline belongs to. |
Package Repositories
The repositories API allows admins and pipeline group admins to view, create and update a package repository.
The package repository config object
Available since v16.12.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | Each repository is associated with an id by which it can be referenced in the . If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update. |
name |
String | The global name of the repository. |
plugin_metadata |
Object | The plugin metadata provides information about the plugin. |
configuration |
Object | The list of properties (key-value pairs) to be provided for using the plugin. |
Get all Repositories
$ curl 'https://ci.example.com/go/api/admin/repositories' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
}
},
"_embedded": {
"package_repositories": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"repo_id": "dd8926c0-3b4a-4c9e-8012-957b179cec5b",
"name": "repository",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [
{
"key": "REPO_URL",
"value": "http://sample-repo"
}
],
"_embedded": {
"packages": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/6bba891e-2675-49af-b16d-200bd6c6801e"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "package",
"id": "6bba891e-2675-49af-b16d-200bd6c6801e"
}
]
}
}
]
}
}
Lists all available package repositories in cruise-config.xml.
Available since v16.12.0.
HTTP Request
GET /go/api/admin/repositories
Returns
A list of repository objects
Get a Repository
$ curl 'https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v1+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/dd8926c0-3b4a-4c9e-8012-957b179cec5b"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"repo_id": "dd8926c0-3b4a-4c9e-8012-957b179cec5b",
"name": "repository",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [
{
"key": "REPO_URL",
"value": "http://sample-repo"
}
],
"_embedded": {
"packages": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/packages/6bba891e-2675-49af-b16d-200bd6c6801e"
},
"doc": {
"href": "https://api.gocd.org/#packages"
},
"find": {
"href": "https://ci.example.com/go/api/admin/packages/:package_id"
}
},
"name": "package",
"id": "6bba891e-2675-49af-b16d-200bd6c6801e"
}
]
}
}
Get a repository for a specified id
Available since v16.12.0.
HTTP Request
GET /go/api/admin/repositories/:repo_id
Returns
A repository object
Create a Repository
$ curl -i "https://ci.example.com/go/api/admin/repositories/" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"repo_id": "repository-id",
"name": "repo.name",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [{
"key": "REPO_URL",
"value": "http://sample"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/repository-id"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"repo_id": "repository-id",
"name": "repo.name",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [
{
"key": "REPO_URL",
"value": "http://sample"
}
],
"_embedded": {
"packages": [
]
}
}
Create the repository configuration in cruise-config.xml.
Available since v16.12.0.
HTTP Request
POST /go/api/admin/repositories
Returns
A new repository object.
Edit a repository
$ curl -i "https://ci.example.com/go/api/admin/repositories/repository-id" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/vnd.go.cd.v1+json' \
-H 'If-Match: "e34c022772eff57ec53b6d50853be343"' \
-X PUT -d '{
"repo_id": "repository-id",
"name": "repo.name",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [{
"key": "REPO_URL",
"value": "http://updatedrepo"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "122cd7ec0319b015653cac9a056063a7"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/repositories/repository-id"
},
"doc": {
"href": "https://api.gocd.org/#package-repositories"
},
"find": {
"href": "https://ci.example.com/go/api/admin/repositories/:repo_id"
}
},
"repo_id": "repository-id",
"name": "repo.name",
"plugin_metadata": {
"id": "deb",
"version": "1"
},
"configuration": [
{
"key": "REPO_URL",
"value": "http://updatedrepo"
}
],
"_embedded": {
"packages": [
]
}
}
Update package repository for specified repository id.
Available since v16.12.0.
HTTP Request
PUT /go/api/admin/repositories/:repo_id
Returns
The updated repository object.
Delete a repository
$ curl -i "https://ci.example.com/go/api/admin/repositories/repository-id" \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message": "The package repository 'repository-id' was deleted successfully."
}
Deletes a package repository from the config XML if its packages are not associated with any pipeline.
Available since v16.12.0.
HTTP Request
DELETE /go/api/admin/repositories/:repo_id
Returns
A message confirmation if the repository was deleted.
Permissions
The permissions API allows users to fetch the permissions for the GoCD entities.
Permissions
$ curl 'http://ci.example.com/go/api/auth/permissions' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"permissions": {
"environment": {
"view": [ "DEV", "UAT", "QA", "PROD" ],
"administer": [ "DEV" ]
},
"config_repo": {
"view": [ "dev-pipelines-repo", "prod-pipelines-repo" ],
"administer": [ "dev-pipelines-repo" ]
},
"cluster_profile": {
"view": [ "dev-cluster", "prod-cluster" ],
"administer": [ "dev-cluster" ]
},
"elastic_agent_profile": {
"view": [ "build-agent", "deploy-agent" ],
"administer": [ "build-agent" ]
}
}
}
The API supports the following query params:
| Param Name | Description |
|---|---|
type |
The type of the gocd entity. When type is specified, GoCD will return the permissions only for the requested type. |
Possible values are environment, config_repo, cluster_profile, elastic_agent_profile. |
Available since v20.1.0.
HTTP Request
GET /go/api/auth/permissions
Returns
A map of entity and permissions.
Pipeline Config
The pipeline config API allows users with administrator role to manage pipeline config.
The pipeline config object
Available since v15.3.0.
| Attribute | Type | Description |
|---|---|---|
group |
String | The name of the pipeline group to which this pipeline belongs. Since v19.10.0. |
label_template |
String | The label template to customise the pipeline instance label. Both of material names and ${COUNT} are available in the label_template. Defaults to ${COUNT}. |
lock_behavior |
String | Define the pipeline lock behavior. Can be one of lockOnFailure, unlockWhenFinished or none (default). Since v17.12.0. |
name |
String | The name of the pipeline. |
template |
String | The name of the template used by pipeline. You MUST specify atleast one stage in stages, or template. |
origin |
Object | The origin of the pipeline. Can be either gocd origin for pipelines defined in cruise-config.xml or config_repo origin for pipelines defined remotely in config repository. Since v17.4.0. |
parameters |
Array | The list of parameters to be used for substitution in a pipeline or pipeline template. |
environment_variables |
Array | The list of environment variables that will be passed to all tasks (commands) that are part of this pipeline. |
materials |
Array | The list of materials to be used by pipeline. You MUST specify atleast one material. |
stages |
Array | The list of stages. You MUST specify atleast one stage in stages, or template. |
tracking_tool |
Object | The tracking tool can be used to specify links to an issue tracker. |
timer |
Object | The timer specifies cron-like schedule to build pipeline. |
The pipeline parameter object
{
"parameters": [
{
"name": "VERSION",
"value": "15.2.0"
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the parameter. |
value |
String | The value of the parameter. |
The environment variable object
{
"environment_variables": [
{
"name": "USERNAME",
"value": "admin",
"secure": false
},
{
"name": "PASSWORD",
"encrypted_value": "1f3rrs9uhn63hd",
"secure": true
},
{
"name": "SSH_PASSPHRASE",
"value": "p@ssw0rd",
"secure": true
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the environment variable. |
value |
String | The value of the environment variable. You MUST specify one of value or encrypted_value. |
encrypted_value |
String | The encrypted value of the environment variable. You MUST specify one of value or encrypted_value. |
secure |
Boolean | Whether environment variable is secure or not. When set to true, encrypts the value if one is specified. The default value is false. |
The pipeline material object
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a material. Can be one of git, svn, hg, p4, tfs, dependency, package, plugin. |
attributes |
Object | The attributes for each material type. |
The git material attributes
{
"materials": [
{
"type": "git",
"attributes": {
"name": "api-docs",
"url": "https://github.com/gocd/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"destination": "api.go.cd",
"auto_update": true,
"filter": {
"ignore": [
"**/*.xml",
"**/*.html"
]
},
"invert_filter": true,
"submodule_folder": null,
"shallow_clone": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
url |
String | The URL of the git repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
branch |
String | The git branch to build. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
auto_update |
Boolean | Whether to poll for new changes or not. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Since v16.7.0. |
submodule_folder |
String | The git submodule in the git repository. |
shallow_clone |
Boolean | Clone with -n (–depth) option if set to true. Since v16.3.0. |
The subversion material attributes
{
"materials": [
{
"type": "svn",
"attributes": {
"name": "svn",
"url": "svn://svn.example.com/myProject/trunk",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A=",
"destination": "myProject",
"filter": null,
"invert_filter": true,
"auto_update": true,
"check_externals": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
url |
String | The URL of the subversion repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Since v16.7.0. |
auto_update |
Boolean | Whether to poll for new changes or not. |
check_externals |
Boolean | Whether the changes of the externals will trigger the pipeline automatically or not. |
The mercurial material attributes
{
"materials": [
{
"type": "hg",
"attributes": {
"name": "api-docs",
"url": "http://hg.example.com/hg/api.go.cd",
"username": "bob",
"encrypted_password": "asdifgrrz6a=",
"branch": "feature",
"destination": "api-docs",
"filter": null,
"invert_filter": true,
"auto_update": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
url |
String | The URL of the mercurial repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
encrypted_password |
String | The encrypted password for the specified user. Since v19.4.0. |
branch |
String | The mercurial branch to build. Since v19.4.0. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Since v16.7.0. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The perforce material attributes
{
"materials": [
{
"type": "p4",
"attributes": {
"name": "api-docs",
"port": "p4.example.com:8080",
"use_tickets": true,
"view": "sample_view",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A=",
"destination": "api-docs",
"filter": null,
"invert_filter": true,
"auto_update": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
port |
String | Perforce server connection to use ([transport:]host:port). |
use_tickets |
Boolean | Whether to work with the Perforce tickets or not. |
view |
String | The Perforce view. |
username |
String | The username to be used. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Since v16.7.0. |
auto_update |
Boolean | Whether to poll for new changes or not. |
The tfs material attributes
{
"materials": [
{
"type": "tfs",
"attributes": {
"name": "tfs",
"url": "http://tfs.exampe.com:8000/tfs",
"project_path": "$/",
"domain": "corporate/domain",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A=",
"destination": "tfs_destination",
"auto_update": true,
"filter": null,
"invert_filter": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
url |
String | The URL for the Collection on the TFS Server. |
project_path |
String | The project path within the TFS collection. |
domain |
String | The domain name for TFS authentication credentials. |
username |
String | The username of the account to access the TFS collection. |
password |
String | The password of the account to access the TFS collection. |
encrypted_password |
String | The encrypted password of the account to access the TFS collection. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
auto_update |
Boolean | Whether to poll for new changes or not. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Since v16.7.0. |
The dependency material attributes
{
"materials": [
{
"type": "dependency",
"attributes": {
"name": "dependency",
"pipeline": "upstream",
"stage": "upstream_stage",
"auto_update": true,
"ignore_for_scheduling": false
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of this material. |
pipeline |
String | The name of a pipeline that this pipeline depends on. |
stage |
String | The name of a stage which will trigger this pipeline once it is successful. |
auto_update |
Boolean | Whether to poll for new changes or not. |
ignore_for_scheduling |
Boolean | Whether the pipeline should be triggered when there are changes in this material. Since v19.10.0. |
The package material attributes
{
"materials": [
{
"type": "package",
"attributes": {
"ref": "e289f497-057b-46bc-bb69-8043454f5c1b"
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique package repository id. |
The plugin material attributes
{
"materials": [
{
"type": "plugin",
"attributes": {
"ref": "5e3612f7-6aa1-4d75-a9b7-6aeb52d98012",
"filter": null,
"invert_filter": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique scm plugin repository id. |
destination |
String | The directory (relative to the pipeline directory) in which source code will be checked out. |
filter |
Object | The filter specifies files in changesets that should not trigger a pipeline automatically. |
invert_filter |
Boolean | Invert filter to enable whitelist. Updated in v20.8.0. |
The filter object
{
"filter": {
"ignore": [
"README.md",
"docs/**.html"
]
}
}
| Attribute | Type | Description |
|---|---|---|
ignore |
String | The pattern for the files to be ignored. |
The stage object
{
"stages": [
{
"name": "my_stage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"approval": {
"type": "success",
"authorization": {
"roles": [
],
"users": [
]
}
},
"environment_variables": [
],
"jobs": [
]
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the stage. |
fetch_materials |
Boolean | Whether to perform material update/checkout. |
clean_working_directory |
Boolean | Whether to delete the working directory every time. |
never_cleanup_artifacts |
Boolean | Never cleanup artifacts for this stage, if purging artifacts is configured at the Server Level. |
approval |
Object | The approval specifies how stage should be triggered. Can be one of manual, success. |
environment_variables |
Array | The list of of environment variables defined here are set on the agents and can be used within your stage. |
jobs |
Array | The list of jobs. |
The approval object
{
"approval": {
"type": "success",
"allow_only_on_success": true,
"authorization": {
"roles": [
],
"users": [
]
}
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the approval on which stage will trigger. Can be one of success, manual. |
allow_only_on_success |
Boolean | Setting this attribute to true will ensure that the stage can triggered only if the previous stage (if any) has succeeded. Default is false. Since v19.8.0. |
authorization |
Object | The authorization under an approval with a manual or success type to specify who can approve this stage. |
The authorization object
{
"authorization": {
"roles": [
],
"users": [
]
}
}
| Attribute | Type | Description |
|---|---|---|
users |
Array | The list of users authorized to operate (run) on this stage. |
roles |
Array | The list of roles authorized to operate (run) on this stage. |
The job object
{
"jobs": [
{
"name": "my_job",
"run_instance_count": null,
"timeout": 0,
"environment_variables": [
],
"resources": [
"Linux",
"Java"
],
"tasks": [
]
},
{
"name": "unit_test",
"run_instance_count": null,
"timeout": 0,
"environment_variables": [
],
"elastic_profile_id": "docker.unit-test",
"tasks": [
]
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the job. |
run_instance_count |
Number/String | The number of jobs to run. If set to null (default), one job will be created. If set to the literal string all, the job will be run on all agents. If set to a positive integer, the specified number of jobs will be created. Can be one of null, Integer, all. |
timeout |
Number | The time period(in minute) after which the job will be terminated by GoCD if it has not generated any output. |
environment_variables |
Array | The list of environment variables defined here are set on the agents and can be used within your tasks. |
resources |
Array | The list of (String) resources that specifies the resource which the job requires to build. MUST NOT be specified along with elastic_profile_id. |
tasks |
Array | The list of tasks that will run as part of the job. |
tabs |
Array | The list of tabs which let you add custom tabs within the job details page. |
artifacts |
Array | The list of artifacts specifies what files the agent will publish to the server. |
elastic_profile_id |
String | The id of the elastic profile, specifying this attribute would run the job on an elastic agent asociated with this profile. MUST NOT be specified along with resources. Since v16.10.0. |
The task object
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a task. Can be one of exec, ant, nant, rake, fetch, pluggable_task. |
attributes |
Object | The attributes for each task type. |
The exec task attributes
{
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "make",
"arguments": [
"-j3",
"docs",
"instal"
],
"working_directory": null
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
command |
String | The name of the executable. If the executable is not on PATH, you may also specify the full path. |
arguments |
Array | The list of arguments to be passed to the executable. |
working_directory |
String | The directory in which the executable is to be executed. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
The ant task attributes
{
"tasks": [
{
"type": "ant",
"attributes": {
"run_if": [
"passed"
],
"working_directory": "script/build",
"build_file": null,
"target": null
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
build_file |
String | The path to Ant build file. |
target |
String | The Ant target(s) to run. |
working_directory |
String | The directory in which Ant is invoked. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
The nant task attributes
{
"tasks": [
{
"type": "nant",
"attributes": {
"run_if": [
"passed"
],
"working_directory": "script/build/123",
"build_file": null,
"target": null,
"nant_path": null
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
build_file |
String | The path to NAnt build file. |
target |
String | The NAnt target(s) to run. |
nant_path |
String | This is the directory where the nant.exe executable is located. By default GoCD will look for nant.exe in the PATH. |
working_directory |
String | The directory in which NAnt is invoked. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
The rake task attributes
{
"tasks": [
{
"type": "rake",
"attributes": {
"run_if": [
"passed"
],
"working_directory": "sample-project",
"build_file": null,
"target": null
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
build_file |
String | The path to rake file. Defaults to rakefile. |
target |
String | The rake target(s) to run. If not specified, rake runs the default target in the file specified by build_file. |
working_directory |
String | The directory from which rake is invoked. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
The fetch task attributes
{
"tasks": [
{
"type": "fetch",
"attributes": {
"artifact_origin": "gocd",
"run_if": [
"passed"
],
"pipeline": "upstream",
"stage": "upstream_stage",
"job": "upstream_job",
"is_source_a_file": false,
"source": "result",
"destination": "test"
}
},
{
"type": "fetch",
"attributes": {
"artifact_origin": "external",
"pipeline": "some-upstream-pipeline",
"stage": "defaultStage",
"job": "defaultJob",
"artifact_id": "s3",
"configuration": [
{
"key": "dest_on_agent",
"value": "artifact"
}
]
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
artifact_origin |
String | Origin indicates whether the artifact to fetch is on the GoCD server or in an external repository. Can be one of gocd, external. |
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
pipeline |
String | The name of direct upstream pipeline or ancestor pipeline of one of the upstream pipelines on which the pipeline of the job depends on. . |
stage |
String | The name of the stage to fetch artifacts from. |
job |
String | The name of the job to fetch artifacts from. |
source |
String | The path of the artifact directory or file of a specific job, relative to the sandbox directory. If the directory or file does not exist, the job is failed. Should be specified if origin is gocd. |
is_source_a_file |
Boolean | Whether source is a file or directory. Should be specified if origin is gocd. |
destination |
String | The path of the directory where the artifact is fetched to. Should be specified if origin is gocd. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
artifact_id |
String | The external artifact that was published by an upstream pipeline or stage. Should be specified if origin is external. |
configuration |
Array | A list of key-value pairs which defines the plugin configuration. Should be specified if origin is external. |
The pluggable task object
{
"tasks": [
{
"type": "pluggable_task",
"attributes": {
"configuration": [
{
"key": "ConverterType",
"value": "jsunit"
}
],
"run_if": [
"passed"
],
"plugin_configuration": {
"id": "xunit.converter.task.plugin",
"version": "1"
},
"on_cancel": null
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
run_if |
Array | The run_if condition specifies when a task should be allowed to run. Can be one of passed, failed, any. |
plugin_configuration |
Object | The plugin configuration contains id of the plugin and version number. |
configuration |
Array | A list of key-value pairs which defines the plugin configuration. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
The tab object
{
"tabs": [
{
"name": "cobertura",
"path": "target/site/cobertura/index.html"
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the tab which will appear in the Job detail page. |
path |
String | The relative path of a file in the server artifact destination directory of the job that will be render in the tab. |
The pipeline config artifact object
{
"artifacts": [
{
"source": "target",
"destination": "result",
"type": "build"
},
{
"source": "test",
"destination": "res1",
"type": "test"
},
{
"artifact_id": "docker-image",
"store_id": "dockerhub",
"type": "external",
"configuration": [
{
"key": "Image",
"value": "gocd/gocd-server"
},
{
"key": "Tag",
"value": "v${GO_PIPELINE_COUNTER}"
}
]
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the artifact. Can be one of test, build, external. |
source |
String | The file or folder to publish to the server. Should be specified if type is either test or build. |
destination |
String | The destination is relative to the artifacts folder of the current job 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 either test or build. |
id |
String | The artifact id for an external artifact. This id can be used later in a downstream fetch task. Should be specified if type is external. |
store_id |
String | The artifact store id referencing an existing global artifact store. Should be specified if type is external. |
configuration |
Array | A list of key-value pairs which defines the plugin configuration. Should be specified if type is external. |
The timer object
{
"timer": {
"spec": "0 0 22 ? * MON-FRI",
"only_on_changes": true
}
}
| Attribute | Type | Description |
|---|---|---|
spec |
String | The cron-like schedule to build the pipeline. |
only_on_changes |
Boolean | Run only if the pipeline hasn’t previously run with the latest material(s). |
The tracking tool object
{
"tracking_tool": {
"type": "generic",
"attributes": {
"url_pattern": "https://github.com/gocd/api.go.cd/issues/${ID}",
"regex": "##(d+)"
}
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the tracking tool is generic. |
attributes |
Object | The attributes of the tracking tool. See attributes for generic. |
The generic tracking tool object
{
"attributes": {
"url_pattern": "https://github.com/gocd/api.go.cd/issues/${ID}",
"regex": "##(d+)"
}
}
| Attribute | Type | Description |
|---|---|---|
url_pattern |
String | In generic tracking tool, the URI to your tracking tool. |
regex |
String | In generic tracking tool, the regular expression to identify card or bug numbers from your checkin comments. |
The config repo origin object
{
"_links": {
"self": {
"href": "http://localhost:8153/go/api/admin/config_repos/repo1"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "http://localhost:8153/go/api/admin/config_repos/:id"
}
},
"type": "config_repo",
"id": "repo1"
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of origin. Can be either gocd or config_repo. |
id |
String | The identifier of the config repository. This attribute is only available if type of the origin is config_repo. |
Get pipeline config
$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v11+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "e064ca0fe5d8a39602e19666454b8d77"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:name"
}
},
"label_template" : "${COUNT}",
"lock_behavior" : "lockOnFailure",
"name" : "new_pipeline",
"template" : null,
"group": "new_group",
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"parameters" : [ ],
"environment_variables" : [ ],
"materials" : [ {
"type" : "git",
"attributes" : {
"url" : "git@github.com:sample_repo/example.git",
"destination" : "dest",
"filter" : null,
"invert_filter" : false,
"name" : null,
"auto_update" : true,
"branch" : "master",
"submodule_folder" : null,
"shallow_clone" : false
}
} ],
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
}]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"artifact_origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ],
"tracking_tool" : null,
"timer" : null
}
Gets pipeline config for specified pipeline name.
Updated to version v11 since v20.08.0.
Available since v15.3.0.
HTTP Request
GET /go/api/admin/pipelines/:pipeline_name
Returns
Edit pipeline config
$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v11+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
-X PUT \
-d '{
"label_template": "${COUNT}",
"lock_behavior": "unlockWhenFinished",
"name": "my_pipeline",
"template": null,
"group": "new_group",
"materials": [
{
"type": "git",
"attributes": {
"url": "https://github.com:sample_repo/example.git",
"username": "bob",
"password": "pass",
"destination": "dest",
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": true,
"branch": "master",
"submodule_folder": null,
"shallow_clone": true
}
}
],
"stages": [
{
"name": "defaultStage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"approval": {
"type": "success",
"authorization": {
"roles": [],
"users": []
}
},
"environment_variables": [],
"jobs": [
{
"name": "defaultJob",
"run_instance_count": null,
"timeout": 0,
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "ls",
"working_directory": null
}
}
],
"artifacts": [
{
"type": "external",
"artifact_id": "docker-image",
"store_id": "dockerhub",
"configuration": [
{
"key": "Image",
"value": "gocd/gocd-server"
},
{
"key": "Tag",
"value": "v${GO_PIPELINE_COUNTER}"
}
]
}
]
}
]
},
{
"name": "s2",
"jobs": [
{
"name": "j2",
"tasks": [
{
"type": "fetch",
"attributes": {
"artifact_origin": "external",
"pipeline": "",
"stage": "defaultStage",
"job": "defaultJob",
"artifact_id": "docker-image"
}
}
]
}
]
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/my_pipeline"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:name"
}
},
"label_template" : "${COUNT}",
"lock_behavior" : "lockOnFailure",
"name" : "new_pipeline",
"template" : null,
"group": "new_group",
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"parameters" : [ ],
"environment_variables" : [ ],
"materials" : [ {
"type" : "git",
"attributes" : {
"url" : "git@github.com:sample_repo/example.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"destination" : "dest",
"filter" : null,
"invert_filter" : false,
"name" : null,
"auto_update" : true,
"branch" : "master",
"submodule_folder" : null,
"shallow_clone" : false
}
} ],
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
}]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"artifact_origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ],
"tracking_tool" : null,
"timer" : null
}
Update pipeline config for specified pipeline name.
Updated to version v11 since v20.08.0.
Available since v15.3.0.
HTTP Request
PUT /go/api/admin/pipelines/:pipeline_name
Returns
The updated pipeline config object.
Create a pipeline
$ curl 'https://ci.example.com/go/api/admin/pipelines' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v11+json' \
-H 'Content-Type: application/json' \
-H 'X-pause-pipeline: true' \
-H 'X-pause-cause: "to have more control over when to start the pipeline after reviewing it"' \
-X POST -d '{ "group": "first",
"pipeline": {
"label_template": "${COUNT}",
"lock_behavior": "lockOnFailure",
"name": "new_pipeline",
"template": null,
"materials": [
{
"type": "git",
"attributes": {
"url": "git@github.com:sample_repo/example.git",
"destination": "dest",
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": true,
"branch": "master",
"submodule_folder": null,
"shallow_clone": true
}
}
],
"stages": [
{
"name": "defaultStage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"approval": {
"type": "success",
"authorization": {
"roles": [],
"users": []
}
},
"environment_variables": [],
"jobs": [
{
"name": "defaultJob",
"run_instance_count": null,
"timeout": 0,
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "ls",
"working_directory": null
}
}
],
"artifacts": [
{
"type": "external",
"artifact_id": "docker-image",
"store_id": "dockerhub",
"configuration": [
{
"key": "Image",
"value": "gocd/gocd-server"
},
{
"key": "Tag",
"value": "v${GO_PIPELINE_COUNTER}"
}
]
}
]
}
]
},
{
"name": "s2",
"jobs": [
{
"name": "j2",
"tasks": [
{
"type": "fetch",
"attributes": {
"artifact_origin": "external",
"pipeline": "",
"stage": "defaultStage",
"job": "defaultJob",
"artifact_id": "docker-image"
}
}
]
}
]
}
]
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/new_pipeline"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:name"
}
},
"label_template" : "${COUNT}",
"lock_behavior" : "lockOnFailure",
"name" : "new_pipeline",
"template" : null,
"group": "new_group",
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"parameters" : [ ],
"environment_variables" : [ ],
"materials" : [ {
"type" : "git",
"attributes" : {
"url" : "git@github.com:sample_repo/example.git",
"destination" : "dest",
"filter" : null,
"invert_filter" : false,
"name" : null,
"auto_update" : true,
"branch" : "master",
"submodule_folder" : null,
"shallow_clone" : false
}
} ],
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
}]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"artifact_origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ],
"tracking_tool" : null,
"timer" : null
}
Create a pipeline.
Updated to version v11 since v20.08.0.
Available since v15.3.0.
HTTP Request
POST /go/api/admin/pipelines
Returns
A new pipeline config object.
Delete a pipeline
$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v11+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
{
"message": "Pipeline 'my_pipeline' was deleted successfully."
}
Deletes a pipeline from the config XML.
Updated to version v11 since v20.08.0.
Available since v16.6.0.
HTTP Request
DELETE /go/api/admin/pipelines/:pipeline_name
Returns
A message confirmation if the pipeline was deleted.
Extract template from pipeline
$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline/extract_to_template' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v11+json' \
-H 'Content-Type: application/json' \
-X PUT \
-d '{
"template_name": "new-template-name"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v11+json; charset=utf-8
ETag: "d4fe83677faaddcbf69c580ffb7409f7"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/clone1"
},
"doc" : {
"href" : "https://api.gocd.org/#pipeline-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"label_template" : "${COUNT}",
"lock_behavior" : "none",
"name" : "my_pipeline",
"template" : "new-template-name",
"group" : "group",
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/#get-configuration"
}
},
"type" : "gocd"
},
"parameters" : [ ],
"environment_variables" : [ ],
"materials" : [ {
"type" : "git",
"attributes" : {
"url" : "git@github.com:sample_repo/example.git",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"destination" : "dest",
"filter" : null,
"invert_filter" : false,
"name" : null,
"auto_update" : true,
"branch" : "master",
"submodule_folder" : null,
"shallow_clone" : false
}
} ],
"stages" : null,
"tracking_tool" : null,
"timer" : null
}
The Extract Template API will create a new template out of the given pipeline and update the pipeline to use the same template.
Available since v19.11.0.
HTTP Request
PUT /go/api/admin/pipelines/:pipeline_name/extract_to_template
Returns
The updated pipeline config object.
Pipeline Group Config
The Pipeline Group Config API allows admin users to manage pipeline groups.
The pipeline group object
Available since v18.10.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the pipeline group. |
authorization |
Object | The authorization configuration for the pipeline group. |
pipelines |
Array | The list of pipelines that belong to the pipeline group. |
The pipeline group authorization configuration
Available since v18.10.0.
| Attribute | Type | Description |
|---|---|---|
view |
Object | The list of users and roles with view permission for this pipeline group. |
operate |
Object | The list of users and roles with operate permission for this pipeline group. |
admins |
Object | The list of users and roles with admin permission for this pipeline group. |
Get all pipeline groups
$ curl 'https://ci.example.com/go/api/admin/pipeline_groups' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups"
},
"doc" : {
"href" : "https://api.go.cd/current/#pipeline-group-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
}
},
"_embedded" : {
"groups" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
},
"doc" : {
"href" : "https://api.go.cd/current/#pipeline-group-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
}
},
"name" : "first",
"authorization" : {
"view" : {
"users" : [ "operate" ],
"roles" : [ ]
},
"admins" : {
"users" : [ "operate" ],
"roles" : [ ]
}
},
"pipelines" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc" : {
"href" : "https://api.gocd.org/#pipeline-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name" : "up42"
} ]
} ]
}
}
Available since v18.10.0.
HTTP Request
GET /go/api/admin/pipeline_groups
Returns
A list of pipeline group objects.
Get a pipeline group
$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "17f5a9edf150884e5fc4315b4a7814cd"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
},
"doc" : {
"href" : "https://api.go.cd/current/#pipeline-group-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
}
},
"name" : "first",
"authorization" : {
"view" : {
"users" : [ "operate" ],
"roles" : [ ]
},
"admins" : {
"users" : [ "operate" ],
"roles" : [ ]
}
},
"pipelines" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc" : {
"href" : "https://api.gocd.org/#pipeline-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name" : "up42"
} ]
}
Gets config for specified pipeline group.
Available since v18.10.0.
HTTP Request
GET /go/api/admin/pipeline_groups/:group_name
Returns
Create a pipeline group
$ curl 'https://ci.example.com/go/api/admin/pipeline_groups' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name": "second",
"authorization": {
"view": {
"users": ["alice"],
"roles": ["role"]
},
"operate": {
"users": ["alice"]
},
"admins": {
"users": ["bob"]
}
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "f35e562b555dbbba2c92f44ebcf58c83"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipeline_groups/second"
},
"doc": {
"href": "https://api.go.cd/current/#pipeline-group-config"
},
"find": {
"href": "http://ci.example.com/go/api/admin/pipeline_groups/:group_name"
}
},
"name": "second",
"authorization": {
"view": {
"users": ["alice"],
"roles": ["role"]
},
"operate": {
"users": ["alice"],
"roles": [ ]
},
"admins": {
"users": ["bob"],
"roles": [ ]
}
},
"pipelines": [ ]
}
Create a pipeline group.
Available since v18.10.0.
HTTP Request
POST /go/api/admin/pipeline_groups
Returns
The new pipeline group object.
Update a pipeline group
Update authorization config of the specified pipeline group.
$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "17f5a9edf150884e5fc4315b4a7814cd"' \
-X PUT \
-d '{
"name": "first",
"authorization": {
"view": {
"users": ["alice"],
"roles": ["role"]
},
"operate": {
"users": ["alice"]
},
"admins": {
"users": ["bob"]
}
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "ae1d9184358c297a23118fe0e0e64c50"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/first"
},
"doc" : {
"href" : "https://api.go.cd/current/#pipeline-group-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipeline_groups/:group"
}
},
"name" : "first",
"authorization" : {
"view" : {
"users" : [ "alice" ],
"roles" : [ "role" ]
},
"operate": {
"users" : [ "alice" ],
"roles" : [ ]
},
"admins" : {
"users" : [ "bob" ],
"roles" : [ ]
}
},
"pipelines" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc" : {
"href" : "https://api.gocd.org/#pipeline-config"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name" : "up42"
} ]
}
Available since v18.10.0.
HTTP Request
PUT /go/api/admin/pipeline_groups/:group_name
Returns
The updated pipeline group object.
Delete a pipeline group
$ curl 'https://ci.example.com/go/api/admin/pipeline_groups/first' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message": "The Pipeline group 'first' was deleted successfully."
}
Deletes the pipeline group.
Available since v18.10.0.
HTTP Request
DELETE /go/api/admin/pipeline_groups/:group_name
Returns
A message confirmation if the pipeline group was deleted.
Pluggable SCMs
The pluggable SCM API v4 allows users to view, create and update the SCM object.
The global scm config object
Available since v16.7.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | Each material is associated with an id by which it can be referenced in the pipelines. If the id is not provided during creation, a uuid will be generated. Id is mandatory while providing data for update. |
name |
String | The global name of the material. |
auto_update |
Boolean | Whether the material is set to poll for new changes. |
origin |
Object | The origin of the pluggable SCM. Can be either gocd origin for pluggable SCMs defined in cruise-config.xml or config_repo origin for pluggable SCMs defined remotely in config repository. Since v20.9.0. |
plugin_metadata |
Object | The plugin metadata provides information about the plugin. |
configuration |
Object | The list of properties (key-value pairs) to be provided for using the plugin. |
The plugin metadata object
{
"plugin_metadata": {
"id": "github.pr",
"version": "1.1"
}
}
| Attribute | Type | Description |
|---|---|---|
id |
String | The plugin id. |
version |
String | The current version of the plugin. |
The configuration property object
{
"configuration": [
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "1f3rrs9uhn63hd"
},
{
"key": "url",
"value": "https://github.com/sample/example.git"
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | The name of the property key. |
value |
String | The value of the property. You MUST specify one of value or encrypted_value. |
encrypted_value |
String | The encrypted value of the property. You MUST specify one of value or encrypted_value. |
Get all Pluggable SCM materials
$ curl 'https://ci.example.com/go/api/admin/scms' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/scms"
},
"doc": {
"href": "https://api.gocd.org/#scms"
}
},
"_embedded": {
"scms": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/scms/scmName"
},
"doc": {
"href": "https://api.gocd.org/#scms"
},
"find": {
"href": "https://ci.example.com/go/api/admin/scms/:material_name"
}
},
"id": "912ef7c8-0d82-4a5c-8f42-0a95abe82466",
"name": "scmName",
"plugin_metadata": {
"id": "github.pr",
"version": "1"
},
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"configuration": [
{
"key": "url",
"value": "https://github.com/sample/example.git"
}
]
}
]
}
}
Lists all available pluggable scm materials, these are materials that are present in the in cruise-config.xml.
Updated to version v4 since v20.9.0.
Available since v16.7.0.
HTTP Request
GET /go/api/admin/scms
Returns
A list of SCM objects
Get a Pluggable SCM material
$ curl 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name"
},
"doc": {
"href": "https://api.gocd.org/#scms"
},
"find": {
"href": "https://ci.example.com/go/api/admin/scms/:material_name"
}
},
"id": "scmID",
"name": "pluggable.scm.material.name",
"plugin_metadata": {
"id": "github.pr",
"version": "1"
},
"auto_update": true,
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"configuration": [
{
"key": "url",
"value": "https://github.com/sample/example.git"
},
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}
Gets the SCM object for a specified name.
Updated to version v4 since v20.9.0.
Available since v16.7.0.
HTTP Request
GET /go/api/admin/scms/:material_name
Returns
A SCM object
Create a SCM object
$ curl 'http://ci.example.com/go/api/admin/scms' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json' \
-H 'Content-Type:application/json' \
-X POST -d '{
"id": "scm-id",
"name": "foobar",
"auto_update": true,
"plugin_metadata": {
"id": "github.pr",
"version": "1"
},
"configuration": [
{
"key": "url",
"value": "git@github.com:sample/example.git"
},
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/scms/scmName"
},
"doc": {
"href": "https://api.gocd.org/#scms"
},
"find": {
"href": "https://ci.example.com/go/api/admin/scms/:material_name"
}
},
"id": "scm-id",
"name": "scmName",
"plugin_metadata": {
"id": "github.pr",
"version": "1"
},
"auto_update": true,
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"configuration": [
{
"key": "url",
"value": "https://github.com/sample/example.git"
},
{
"key": "username",
"encrypted_value": "50TVtMW3cBU="
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}
Create a global SCM object.
Updated to version v4 since v20.9.0.
Available since v16.7.0.
HTTP Request
POST /go/api/admin/scms
Returns
A new SCM object.
Update Pluggable SCM object
$ curl 'https://ci.example.com/go/api/admin/scms/scmName' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
-X PUT \
-d '{
"id": "scmID",
"name": "scmName",
"auto_update": true,
"plugin_metadata":
{
"id": "github.pr",
"version": "1"
},
"configuration": [
{
"key": "url",
"value": "git@github.com:sample/example.git"
},
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/scms/scmName"
},
"doc": {
"href": "https://api.gocd.org/#scms"
},
"find": {
"href": "https://ci.example.com/go/api/admin/scms/:material_name"
}
},
"id": "scmID",
"name": "scmName",
"plugin_metadata": {
"id": "github.pr",
"version": "1"
},
"auto_update": true,
"origin" : {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/admin/config_xml"
},
"doc" : {
"href" : "https://api.gocd.org/current/#get-configuration"
}
},
"type" : "gocd"
},
"configuration": [
{
"key": "url",
"value": "https://github.com/sample/example.git"
},
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}
Update global scm configuration for specified scm name.
Updated to version v4 since v20.9.0.
Available since v16.7.0.
HTTP Request
PUT /go/api/admin/scms/:material_name
Returns
The updated SCM object.
Delete a Pluggable SCM material
$ curl -i 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"
{
"message": "Scm with name 'pluggable.scm.material.name' was deleted successfully!"
}
Delete the SCM object with the specified name.
Updated to version v4 since v20.9.0.
Available since v19.8.0.
HTTP Request
DELETE /go/api/admin/scms/:material_name
Returns
A message if the scm is deleted or not.
Usages of a pluggable SCM material
$ curl -i 'https://ci.example.com/go/api/admin/scms/pluggable.scm.material.name/usages' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json;charset=utf-8
{
"_links": {
"self": {
"href": "http://test.host/go/api/admin/scms/pluggable.scm.material.name/usages"
},
"doc": {
"href": "https://api.gocd.org/current/#scms"
},
"find": {
"href": "http://test.host/go/api/admin/scms/:material_name/usages"
}
},
"usages": [
{
"group": "grp1",
"pipeline": "pipeline1"
},
{
"group": "grp2",
"pipeline": "pipeline2"
}
]
}
Gets the list of pipelines and groups which use the specified pluggable SCM as a material.
Updated to version v4 since v20.9.0.
Available since v20.3.0.
HTTP Request
GET /go/api/admin/scms/:material_name/usages
Returns
A list of usage objects.
Pluggable SCM usage object
{
"pipeline": "pipeline_name",
"group": "grp_name"
}
| Attribute | Type | Description |
|---|---|---|
group |
String | The group to which the pipeline belongs to. |
pipeline |
String | The name of the pipeline which uses the pluggable SCM as a material. |
Plugin Settings
The plugin settings API allows admin users with to manage the settings of an installed plugin. The plugin settings are currently stored and retrieved from the database for a plugin.
The plugin settings object
Available since v17.8.0.
| Attribute | Type | Description |
|---|---|---|
plugin_id |
String | Plugin unique identifier. |
configuration |
Object | List of configuration required to configure the plugin settings. |
The plugin settings property object
{
"configuration": [
{
"key": "username",
"value": "admin"
},
{
"key": "password",
"encrypted_value": "1f3rrs9uhn63hd"
},
{
"key": "url",
"value": "https://github.com/sample/example.git"
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | The name of the property key. |
value |
String | The value of the property. You MUST specify one of value or encrypted_value. |
encrypted_value |
String | The encrypted value of the property. You MUST specify one of value or encrypted_value. |
Get Plugin Settings
$ curl 'https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v1+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
},
"doc": {
"href": "https://api.gocd.org/#plugin-settings"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
}
},
"plugin_id": "github.oauth.login",
"configuration": [
{
"key": "consumer_key",
"value": "consumerkey"
},
{
"key": "consumer_secret",
"value": "consumersecret"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
},
{
"key": "server_base_url",
"value": "https://ci.example.com"
}
]
}
Gets the stored plugin settings for the specified plugin id, if the plugin is configured.
Available since v17.9.0.
HTTP Request
GET /go/api/admin/plugin_settings/:plugin_id
Returns
A Plugin Settings object or an error 404 if the plugin was not yet configured.
Create Plugin Settings
$ curl -i 'https://ci.example.com/go/api/admin/plugin_settings' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"plugin_id": "github.oauth.login",
"configuration": [
{
"key": "server_base_url",
"value": "https://ci.example.com"
},
{
"key": "consumer_key",
"value": "consumerkey"
},
{
"key": "consumer_secret",
"value": "consumersecret"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
},
"doc": {
"href": "https://api.gocd.org/#plugin-settings"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
}
},
"plugin_id": "github.oauth.login",
"configuration": [
{
"key": "server_base_url",
"value": "https://ci.example.com"
},
{
"key": "consumer_key",
"value": "consumerkey"
},
{
"key": "consumer_secret",
"value": "consumersecret"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}
Create plugin settings for a plugin based on user inputs. The keys are
dependent on the plugin to be configured. Use the result of
Get plugin info to find the possible keys under
extensions/plugin_settings/configurations.
Available since v17.9.0.
HTTP Request
POST /go/api/admin/plugin_settings
Returns
A new Plugin Settings object.
Update Plugin Settings
$ curl 'https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "05548388f7ef5042cd39f7fe42e85735"' \
-X PUT -d '{
"plugin_id": "github.oauth.login",
"configuration": [
{
"key": "server_base_url",
"value": "https://ci.example.com"
},
{
"key": "consumer_key",
"value": "updated_consumer_key"
},
{
"key": "consumer_secret",
"value": "consumersecret"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/github.oauth.login"
},
"doc": {
"href": "https://api.gocd.org/#plugin-settings"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_settings/:plugin_id"
}
},
"plugin_id": "github.oauth.login",
"configuration": [
{
"key": "server_base_url",
"value": "https://ci.example.com"
},
{
"key": "consumer_key",
"value": "updated_consumer_key"
},
{
"key": "consumer_secret",
"value": "consumersecret"
},
{
"key": "password",
"encrypted_value": "aSdiFgRRZ6A="
}
]
}
Updates plugin settings for the specified plugin id.
Available since v17.9.0.
HTTP Request
PUT /go/api/admin/plugin_settings/:plugin_id
Returns
The updated Plugin Settings object.
Roles
The roles API allows admin users to manage roles or plugin roles. The plugin roles will later be used by the plugin to authorize user for GoCD server.
In order to create Plugin Role authorization configuration is required.
The role object
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the role. |
type |
String | Type of the role. Use gocd to create core role and plugin to create plugin role. |
attributes |
Object | Attributes are used to describes the configuration for gocd role or plugin role. |
policy |
Object | Policy is fine-grained permissions attached to the users belonging to the current role. Since v19.11.0. |
The permission object
| Attribute | Type | Description |
|---|---|---|
permission |
String | The type of permission which can be either allow or deny. |
action |
String | The action that is being controlled via this rule. Can be one of *, view, administer. |
type |
String | The type of entity that the rule is applied on. Can be one of *, environment. |
resource |
String | The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities. |
The GoCD role attributes
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
users |
Array | The list of users belongs to the role. |
The plugin role attributes
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
auth_config_id |
String | The authorization configuration identifier. |
properties |
Array | The list of configuration properties that represent the configuration of this plugin role. |
Get all roles
$ curl 'https://ci.example.com/go/api/admin/security/roles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"_embedded": {
"roles": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "spacetiger",
"type": "gocd",
"attributes": {
"users": ["alice", "bob", "robin"]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
},
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/blackbird"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "blackbird",
"type": "plugin",
"attributes": {
"auth_config_id": "ldap",
"properties": [
{
"key": "UserGroupMembershipAttribute",
"value": "memberOf"
},
{
"key": "GroupIdentifiers",
"value": "ou=admins,ou=groups,ou=system,dc=example,dc=com"
}
]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_B_*"
}]
}
]
}
}
Lists all available roles which includes GoCD role and plugin role.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
GET /go/api/admin/security/roles
Returns
An array of role object.
Get all roles by type
Get all roles by type
$ curl 'https://ci.example.com/go/api/admin/security/roles?type=gocd' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"_embedded": {
"roles": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "spacetiger",
"type": "gocd",
"attributes": {
"users": ["alice", "bob", "robin"]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}
]
}
}
List all available roles of specified type.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
GET /go/api/admin/security/roles?type=:role_type
Returns
An array of role object.
Get a role
$ curl 'https://ci.example.com/go/api/admin/security/roles/blackbird' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/blackbird"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "blackbird",
"auth_config_id": "ldap",
"properties": [
{
"key": "MemberOf",
"value": "ou=blackbird,ou=area51,dc=example,dc=com"
}
],
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}
Gets role for specified role name.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
GET /go/api/admin/security/roles/:role_name
Returns
An array of role object.
Create a GoCD role
$ curl 'https://ci.example.com/go/api/admin/security/roles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name": "new-role",
"type": "gocd",
"attributes" : {
"users": ["bob"]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/new-role"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "new-role",
"type": "gocd",
"attributes": {
"users": ["bob"]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}
Create a GoCD role. A GoCD role is a group of users having same permissions in GoCD.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
POST /go/api/admin/security/roles
Returns
The role object.
Create a plugin role
$ curl 'https://ci.example.com/go/api/admin/security/roles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name": "new-plugin-role",
"type": "plugin",
"attributes": {
"auth_config_id": "ldap",
"properties": [
{
"key": "UserGroupMembershipAttribute",
"value": "memberOf"
},
{
"key": "GroupIdentifiers",
"value": "ou=devs,ou=groups,ou=system,dc=example,dc=com"
}
]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/blackbird1"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "blackbird1",
"type": "plugin",
"attributes": {
"auth_config_id": "ldap",
"properties": [
{
"key": "UserGroupMembershipAttribute",
"value": "memberOf"
},
{
"key": "GroupIdentifiers",
"value": "ou=admins,ou=groups,ou=system,dc=example,dc=com"
}
]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A_*"
}]
}
Plugin role is used to authorize user against external authorization server using authorization plugin.
Prerequisite to create plugin role,
- Install authorization plugin with
can_authorizecapability. - Create authorization configuration.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
POST /go/api/admin/security/roles
Returns
The role object.
Update a role
Update attributes of the role identified by the specified role name.
$ curl 'https://ci.example.com/go/api/admin/security/roles/spacetiger' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"name": "spacetiger",
"type": "gocd",
"attributes": {
"users": ["alice"]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A*"
}]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/spacetiger"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "spacetiger",
"type": "gocd",
"attributes": {
"users": [ "alice" ]
},
"policy": [
{
"permission":"allow",
"action":"view",
"type":"environment",
"resource":"env_A*"
}]
}
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
PUT /go/api/admin/security/roles/:role_name
Returns
The role object.
Delete a role
$ curl 'https://ci.example.com/go/api/admin/security/roles/blackbird' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "The plugin role config 'blackbird' was deleted successfully."
}
Deletes the role.
Updated to version v3 since v19.11.0.
Available since v17.5.0.
HTTP Request
DELETE /go/api/admin/security/roles/:role_name
Returns
A message if the role is deleted or not.
Bulk update roles
$ curl 'https://ci.example.com/go/api/admin/security/roles' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X PATCH \
-d '{
"operations": [
{
"role": "role1",
"users": {
"add": [
"user1",
"user2"
],
"remove": [
"user3",
"user4"
]
}
},
{
"role": "role2",
"users": {
"add": [
"user2"
]
}
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"_embedded": {
"roles": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/role1"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "role1",
"type": "gocd",
"attributes": {
"users": ["user3", "user4", "robin"]
}
},
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/security/roles/role2"
},
"doc": {
"href": "https://api.gocd.org/#roles"
},
"find": {
"href": "https://ci.example.com/go/api/admin/security/roles/:role_name"
}
},
"name": "role2",
"type": "gocd",
"attributes": {
"users": ["alice", "user2"]
}
}
]
}
}
Bulk update roles.
Updated to version v3 since v19.11.0.
Available since v19.1.0.
HTTP Request
PATCH /go/api/admin/security/roles
| Attribute | Type | Description |
|---|---|---|
operations |
Array | The bulk update operations performed on the set of roles. |
Returns
An array of role object of type ‘gocd’.
The bulk update operation attributes
{
"role": "role1",
"users": {
"add": [
"User1",
"User2"
],
"remove": [
"User3",
"User4"
]
}
}
| Attribute | Type | Description |
|---|---|---|
role |
String | The role name which needs to be updated. |
users |
Object | The users to be added/removed for a given role. |
The users to be updated
{
"add": [
"User1",
"User2"
],
"remove": [
"User3",
"User4"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of users that needs to be added to the role. |
remove |
Array | The list of users that needs to be removed from the role. |
Secret Configs
The secret configs API allows users with admin privileges to configure external Secret Managers to lookup for secrets.
The secret config object
Available since v19.6.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the secret config. |
pluginId |
String | The identifier of the plugin to which current secret config belongs. |
configuration |
Array | The list of configuration properties that represent the configuration of this secret config. |
rules |
Array | The list of rules, which allows restricting the usage of the secret config. Referring to the secret config from other parts of configuration is denied by default, an explicit rule should be added to allow a specific resource to refer the secret config. |
description |
String | The description for this secret config. |
The Rule object
Available since v19.6.0.
| Attribute | Type | Description |
|---|---|---|
directive |
String | The type of rule which can be either allow or deny. |
action |
String | The action that is being controlled via this rule. Only refer is supported as of now. |
type |
String | The type of entity that the rule is applied on. Can be one of environment, pipeline_group, pluggable_scm, package_repository, cluster_profile. Updated in v20.9.0. |
resource |
String | The actual entity on which the rule is applied. Resource should be the name of the entity or a wildcard which matches one or more entities. |
Get all secret configs
$ curl 'https://ci.example.com/go/api/admin/secret_configs' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "32628084ef10b0c82a55f8f2f867d8d0"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs"
},
"doc" : {
"href" : "https://api.gocd.org/#secret-configs"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
}
},
"_embedded" : {
"secret_configs" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/demo"
},
"doc" : {
"href" : "https://api.gocd.org/#secret-configs"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
}
},
"id" : "demo",
"plugin_id" : "cd.go.secrets.file-based-plugin",
"description" : "",
"properties" : [ {
"key" : "SecretsFilePath",
"value" : "path/to/secret/file.db"
} ],
"rules" : [ {
"directive" : "allow",
"action" : "refer",
"type" : "pipeline_group",
"resource" : "first"
} ]
} ]
}
}
Lists all available secret configurations.
Updated to version v3 since v20.9.0.
Available since v19.6.0.
HTTP Request
GET /go/api/admin/secret_configs
Returns
An array of secret configs.
Get a secret config
$ curl 'https://ci.example.com/go/api/admin/secret_configs/demo' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "465f3520fa02e65a05844a5a27f83393"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/demo"
},
"doc" : {
"href" : "https://api.gocd.org/#secret-configs"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
}
},
"id" : "demo",
"plugin_id" : "cd.go.secrets.file-based-plugin",
"description" : "",
"properties" : [ {
"key" : "SecretsFilePath",
"value" : "path/to/secret/file.db"
} ],
"rules" : [ {
"directive" : "allow",
"action" : "refer",
"type" : "pipeline_group",
"resource" : "first"
} ]
}
Gets the secret config for the specified id.
Updated to version v3 since v20.9.0.
Available since v19.6.0.
HTTP Request
GET /go/api/admin/secret_configs/:id
Returns
The secret config object.
Create a secret config
$ curl 'https://ci.example.com/go/api/admin/secret_configs' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id" : "demo",
"plugin_id" : "cd.go.secrets.file-based-plugin",
"description" : "",
"properties" : [ {
"key" : "SecretsFilePath",
"value" : "/path/to/secret/file.db"
}],
"rules":[
{
"directive":"allow",
"action":"refer",
"type":"pipeline_group",
"resource":"first"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "f64e700e7d94e6bc36fc56539cfe993d"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/secret-test"
},
"doc" : {
"href" : "https://api.gocd.org/#secret-configs"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
}
},
"id" : "demo",
"plugin_id" : "cd.go.secrets.file-based-plugin",
"description" : "",
"properties" : [ {
"key" : "SecretsFilePath",
"value" : "path/to/secret/file.db"
} ],
"rules" : [ {
"directive" : "allow",
"action" : "refer",
"type" : "pipeline_group",
"resource" : "first"
} ]
}
Creates a secret config.
Updated to version v3 since v20.9.0.
Available since v19.6.0.
HTTP Request
POST /go/api/admin/secret_configs
Returns
The secret config object.
Update a secret config
$ curl 'https://ci.example.com/go/api/admin/secret_configs/secret-test' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "465f3520fa02e65a05844a5a27f83393"' \
-X PUT \
-d '{
"id":"secret-test"
"plugin_id":"cd.go.secrets.file-based-plugin",
"properties": [
{
"key": "SecretsFilePath",
"value": "updated/path/to/secret/file.db"
}
],
"rules":[
{
"directive":"allow",
"action":"refer",
"type":"pipeline_group",
"resource":"first*"
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "3b55fd5294b16a55228de0f9eef98ecb"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/secret-test"
},
"doc" : {
"href" : "https://api.gocd.org/#secret-configs"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/secret_configs/:config_id"
}
},
"id" : "secret-test",
"plugin_id" : "cd.go.secrets.file-based-plugin",
"description" : "",
"properties" : [ {
"key" : "SecretsFilePath",
"value" : "updated/path/to/secret/file.db"
} ],
"rules" : [ {
"directive" : "allow",
"action" : "refer",
"type" : "pipeline_group",
"resource" : "first*"
} ]
}
Update some attributes of a secret config.
Updated to version v3 since v20.9.0.
Available since v19.6.0.
HTTP Request
PUT /go/api/admin/secret_configs/:id
Returns
The updated secret_config object.
Delete a secret config.
$ curl 'https://ci.example.com/go/api/admin/secret_configs/secret-test' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "Secret config with id 'secret-test' was deleted successfully!"
}
Deletes the config.
Updated to version v3 since v20.9.0.
Available since v19.6.0.
HTTP Request
DELETE /go/api/admin/secret_configs/:id
Returns
A message if the secret config is deleted or not.
Siteurls Config
The site urls config API allows admins to setup the server site URL and secure server site URL.
The Site Urls Config Object
Available since v19.11.0.
| Attribute | Type | Description |
|---|---|---|
siteUrl |
String | The site URL will be used by GoCD Server to generate links for emails, feeds, etc. Format: [protocol]://[host]:[port].The protocol can be HTTP ot HTTPs.You need to define the [port] in case GoCD uses a non-standard port. |
secureSiteUrl |
String | 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 specify this attribute with a value of the base HTTPS URL. Format: https://[host]:[port]. |
Get SiteUrls Config
$ curl 'https://ci.example.com/go/api/admin/config/server/site_urls' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/current/#siteurls-config"
},
"self": {
"href": "http://ci.example.com/go/api/admin/config/server/site_urls"
}
},
"site_url" : "http://foo.com",
"secure_site_url" : "https://foo.com"
}
Available since v19.11.0.
HTTP Request
GET /go/api/admin/config/server/site_urls
Returns
Create or Update siteUrls Config
$ curl 'https://ci.example.com/go/api/admin/config/server/site_urls' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"site_url" : "http://siteUrl.com",
"secure_site_url" : "https://secureSiteUrl.com"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#siteurls-config"
},
"self" : {
"href" : "http://ci.example.com/go/api/admin/config/server/site_urls"
}
},
"site_url" : "http://siteUrl.com",
"secure_site_url" : "https://secureSiteUrl.com"
}
Available since v19.11.0.
HTTP Request
POST /go/api/admin/config/server/site_urls
PUT /go/api/admin/config/server/site_urls
Returns
System Admins
The API allows admin users to manage System Admins.
The system admins object
Available since v18.8.0.
| Attribute | Type | Description |
|---|---|---|
roles |
Array | The list of roles having system admin privileges. |
users |
Array | The list of users having system admin privileges. |
Get all system admins
$ curl 'https://ci.example.com/go/api/admin/security/system_admins' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/#system_admins"
},
"self" : {
"href" : "https://ci.example.com/go/api/admin/security/system_admins"
}
},
"roles" : [ "manager"],
"users" : [ "john" , "maria"]
}
Lists all system admins which includes users and roles.
Available since v18.8.0.
HTTP Request
GET /go/api/admin/security/system_admins
Returns
An array of roles and users having system admin privileges.
Update system admins
Update system admins and replace the system admins with roles and users in the request. The list of roles in the update request must be present in roles config.
$ curl 'https://ci.example.com/go/api/admin/security/system_admins' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"users": ["bob", "jdoe", "john"],
"roles": ["manager"]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
ETag: "61406622382e51c2079c11dcbdb978fb"
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/#system_admins"
},
"self" : {
"href" : "https://ci.example.com/go/api/admin/security/system_admins"
}
},
"roles" : [ "manager" ],
"users" : [ "bob" , "jdoe", "john"]
}
Available since v18.8.0.
HTTP Request
PUT /go/api/admin/security/system_admins
Returns
The updated system admins object.
Bulk update system admins
curl 'https://ci.example.com/go/api/admin/security/system_admins' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"operations": {
"users": {
"add": ["user1", "user2"],
"remove": ["admin"]
},
"roles": {
"add": ["xyz"],
"remove": ["role1"]
}
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#system_admins"
},
"self": {
"href": "http://localhost:8153/go/api/admin/security/system_admins"
}
},
"roles": [
"xyz"
],
"users": [
"user1",
"user2"
]
}
Bulk update System Admins.
Available since v19.1.0.
HTTP Request
PATCH /go/api/admin/security/system_admins
| Attribute | Type | Description |
|---|---|---|
operations |
Object | The bulk update operation performed on system admin. |
Returns
The updated system admins object.
The bulk update operation attributes
{
"users": {
"add": [
"User1",
"User2"
],
"remove": [
"User3",
"User4"
]
},
"roles": {
"add": [
"role1",
"role2"
],
"remove": [
"role3",
"role4"
]
}
}
| Attribute | Type | Description |
|---|---|---|
users |
Object | The users to be added/removed. |
roles |
Object | The roles to be added/removed. |
The users to be updated
{
"add": [
"User1",
"User2"
],
"remove": [
"User3",
"User4"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of users that needs to be made system admins. |
remove |
Array | The list of users that needs to be revoked system admin access. |
The roles to be updated
{
"add": [
"role11",
"role2"
],
"remove": [
"role3",
"role4"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of roles that needs to be made system admins. |
remove |
Array | The list of roles that needs to be revoked system admin access. |
Template Config
The template config API allows users with administrator role to manage template config.
The shallow template config object
Available since v16.10.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the template. |
can_edit |
Boolean | This property specifies whether the current user can edit the template configuration. |
can_administer |
Boolean | This property specifies whether the current user can administer the template. |
pipelines |
Array | The list of pipelines using the current template. |
The shallow pipeline config object
Available since v16.10.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the pipeline using the current template. |
can_administer |
Boolean | This property specifies whether the current user can administer the pipeline. |
The template config object
Available since v16.10.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the template. |
stages |
Array | The list of stages. You MUST specify atleast one stage in stages, or template. |
The template authorization object
Available since v18.2.0.
| Attribute | Type | Description |
|---|---|---|
all_group_admins_are_view_users |
Boolean | This property specifies whether the group admins are allowed to view the template configuration. |
admin |
Object | The users and roles that have admin permissions to edit the template configuration. |
view |
Object | The explicitly configured users and roles that have permissions to view the template configuration. |
The authorization object
{
"roles": [
"role1",
"role2"
],
"users": [
"user1",
"user2"
]
}
| Attribute | Type | Description |
|---|---|---|
users |
Array | List of user names that should be granted the specified permission. |
roles |
Array | List of roles that should be granted the specified permission. |
Get all templates
$ curl 'https://ci.example.com/go/api/admin/templates' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/templates"
},
"doc": {
"href": "https://api.gocd.org/#template-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/templates/:template_name"
}
},
"_embedded": {
"templates": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/templates/template1"
},
"doc": {
"href": "https://api.gocd.org/#template-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/templates/:template_name"
}
},
"name": "template1",
"can_edit" : true,
"can_administer" : true,
"_embedded": {
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/pipelines/up42"
},
"doc": {
"href": "https://api.gocd.org/#pipeline-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/pipelines/:pipeline_name"
}
},
"name": "up42",
"can_administer" : true
}
]
}
}
]
}
}
Lists all available templates with the associated pipelines’ names.
Updated to version v7 since v20.2.0.
Available since v16.10.0.
HTTP Request
GET /go/api/admin/templates
Returns
A list of template objects
Get template config
$ curl 'https://ci.example.com/go/api/admin/templates/template.name' \
-u 'username:password' \
-H 'Accept:application/vnd.go.cd.v7+json' \
-i
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "05548388f7ef5042cd39f7fe42e85735"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/templates/template.name"
},
"doc": {
"href": "https://api.gocd.org/#template-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/templates/:template_name"
}
},
"name" : "template.name",
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
} ]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ]
}
Gets template config for specified template name.
Updated to version v7 since v20.2.0.
Available since v16.10.0.
HTTP Request
GET /go/api/admin/templates/:template_name
Returns
A template object
Create template config
$ curl 'https://ci.example.com/go/api/admin/templates' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name": "template",
"stages": [
{
"name": "defaultStage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"environment_variables": [],
"jobs": [
{
"name": "defaultJob",
"run_instance_count": null,
"elastic_profile_id": "elastic_profile_id",
"timeout": 0,
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "ls",
"working_directory": null
}
}
],
"artifacts": [
{
"type": "external",
"artifact_id": "docker-image",
"store_id": "dockerhub",
"configuration": [
{
"key": "Image",
"value": "goose"
},
{
"key": "Tag",
"value": "v${GO_PIPELINE_LABEL}"
}
]
}
]
}
]
},
{
"name": "s2",
"jobs": [
{
"name": "j2",
"tasks": [
{
"type": "fetch",
"attributes": {
"origin": "external",
"pipeline": "",
"stage": "defaultStage",
"job": "defaultJob",
"artifact_id": "docker-image"
}
}
]
}
]
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/templates/template"
},
"doc": {
"href": "https://api.gocd.org/#template-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/templates/:template_name"
}
},
"name" : "template",
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
} ]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ]
}
Creates a template config object.
Updated to version v7 since v20.2.0.
Available since v16.10.0.
HTTP Request
POST /go/api/admin/templates
Returns
A new template object.
Edit template config
$ curl 'https://ci.example.com/go/api/admin/templates/template' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-H 'If-Match: "05548388f7ef5042cd39f7fe42e85735"' \
-H 'Content-Type: application/json' \
-X PUT -d '{
"name": "template",
"stages": [
{
"name": "defaultStage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"environment_variables": [],
"jobs": [
{
"name": "defaultJob",
"run_instance_count": null,
"elastic_profile_id": "elastic_profile_id",
"timeout": 0,
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "ls",
"working_directory": null
}
}
],
"artifacts": [
{
"type": "external",
"artifact_id": "docker-image",
"store_id": "dockerhub",
"configuration": [
{
"key": "Image",
"value": "goose"
},
{
"key": "Tag",
"value": "v${GO_PIPELINE_LABEL}"
}
]
}
]
}
]
},
{
"name": "s2",
"jobs": [
{
"name": "j2",
"tasks": [
{
"type": "fetch",
"attributes": {
"origin": "external",
"pipeline": "",
"stage": "defaultStage",
"job": "defaultJob",
"artifact_id": "docker-image"
}
}
]
}
]
}
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "e89135b38ddbcd9380c83eb524647bdd"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/templates/template"
},
"doc": {
"href": "https://api.gocd.org/#template-config"
},
"find": {
"href": "https://ci.example.com/go/api/admin/templates/:template_name"
}
},
"name" : "template",
"stages" : [ {
"name" : "defaultStage",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "defaultJob",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "exec",
"attributes" : {
"run_if" : [ "passed" ],
"command" : "ls",
"args" : ""
}
} ],
"tabs" : [ ],
"artifacts" : [ {
"type" : "external",
"artifact_id" : "docker-image",
"store_id" : "dockerhub",
"configuration" : [ {
"key" : "Image",
"value" : "gocd/gocd-server"
}, {
"key" : "Tag",
"value" : "v${GO_PIPELINE_LABEL}"
} ]
} ]
} ]
}, {
"name" : "s2",
"fetch_materials" : true,
"clean_working_directory" : false,
"never_cleanup_artifacts" : false,
"approval" : {
"type" : "success",
"authorization" : {
"roles" : [ ],
"users" : [ ]
}
},
"environment_variables" : [ ],
"jobs" : [ {
"name" : "j2",
"run_instance_count" : null,
"timeout" : null,
"environment_variables" : [ ],
"resources" : [ ],
"tasks" : [ {
"type" : "fetch",
"attributes" : {
"origin" : "external",
"pipeline" : "",
"stage" : "defaultStage",
"job" : "defaultJob",
"run_if" : [ ],
"artifact_id" : "docker-image"
}
} ],
"tabs" : [ ],
"artifacts" : [ ]
} ]
} ]
}
Update template config for specified template name.
Updated to version v7 since v20.2.0.
Available since v16.10.0.
HTTP Request
PUT /go/api/admin/template/:template_name
Returns
The updated template object.
Delete a template
$ curl 'https://ci.example.com/go/api/admin/templates/template_name' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"message": "The template 'template_name' was deleted successfully."
}
Deletes a template from the config XML if it is not associated with any pipeline.
Updated to version v7 since v20.2.0.
Available since v16.10.0.
HTTP Request
DELETE /go/api/admin/templates/:template_name
Returns
A message confirmation if the template was deleted.
Get parameters for a template
$ curl 'https://ci.example.com/go/api/admin/templates/template_name/parameters' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "http://go-server-url/go/api/admin/templates/template-name"
},
"doc" : {
"href" : "https://api.gocd.org/#template-config"
},
"find" : {
"href" : "http://go-server-url/go/api/admin/templates/:template_name"
}
},
"name" : "template-name",
"parameters" : [ "resources", "command" ]
}
Returns a list of parameters which needs to be defined while using the same in a pipeline config
Available since v20.2.0.
HTTP Request
GET /go/api/admin/templates/:template_name/parameters
Returns
A list of string.
Get template authorization
$ curl -i 'https://ci.example.com/go/api/admin/templates/template_name/authorization' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"all_group_admins_are_view_users": true,
"admin": {
"roles": [
"xyz"
],
"users": [
]
},
"view": {
"roles": [
],
"users": [
"user"
]
}
}
Returns template authorization for the specified template name.
Available since v18.2.0.
HTTP Request
GET /go/api/admin/templates/:template_name/authorization
Returns
The template authorization object.
Update template authorization
$ curl 'https://ci.example.com/go/api/admin/templates/template_name/authorization' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "d124ed4db70c23110924f488a031c8c9"' \
-X PUT -d '{
"all_group_admins_are_view_users": true,
"admin": {
"roles": [],
"users": [
"user"
]
},
"view": {
"roles": [
"xyz"
],
"users": [
"view"
]
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"all_group_admins_are_view_users": true,
"admin": {
"roles": [
],
"users": [
"user"
]
},
"view": {
"roles": [
"xyz"
],
"users": [
"view"
]
}
}
Update template authorization for the specified template.
Available since v18.2.0.
HTTP Request
PUT /go/api/admin/templates/:template_name/authorization
Returns
The template authorization object.
section_marker_placeholder:Runtime
Access Tokens
Access tokens allow users to make API calls to GoCD using a bearer token instead of username and password.
The access token object
Available since v19.2.0.
| Attribute | Type | Description |
|---|---|---|
description |
String | The user provided description of the token. |
token |
String | The value of the token. This will be rendered only once when the token is created. |
username |
String | The username of the user that created the token. |
revoked |
Boolean | If the token has been revoked. |
revoke_cause |
String | The reason why the token was revoked. |
revoked_at |
Timestamp | The time when the token was revoked. |
revoked_by |
String | The username of the user that revoked the token. |
created_at |
Timestamp | The time when the token was created. |
last_used_at |
Timestamp | The time when the token was last used to authenticate with the server. |
revoked_because_user_deleted |
Boolean | Indicates if the token was revoked because a system adminstrator deleted the user. |
Get all tokens for current user
$ curl 'https://ci.example.com/go/api/current_user/access_tokens' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
}
},
"_embedded" : {
"access_tokens" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/:id"
}
},
"id" : 42,
"description" : "my first token",
"username" : "username",
"revoked" : false,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : "2019-02-20T10:45:10Z",
"last_used_at" : null
} ]
}
}
Lists all tokens belonging to a user.
Available since v19.2.0.
HTTP Request
GET /go/api/current_user/access_tokens
Returns
An array of access token objects.
Get one token for current user
$ curl 'https://ci.example.com/go/api/current_user/access_tokens/42' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/:id"
}
},
"id" : 42,
"description" : "my first token",
"username" : "username",
"revoked" : false,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : "2019-02-20T10:45:10Z",
"last_used_at" : null
}
Gets a token by its unique identifier (id).
Available since v19.2.0.
HTTP Request
GET /go/api/current_user/access_tokens/:id
Returns
Create token for current user
$ curl 'https://ci.example.com/go/api/current_user/access_tokens' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"description": "my first token"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/:id"
}
},
"id" : 42,
"description" : "my first token",
"username" : "username",
"revoked" : true,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : null,
"last_used_at" : null,
"token" : "30bd353a513ef3a2f72f46cc50d2a587b855fa04"
}
Creates a token.
Available since v19.2.0.
HTTP Request
POST /go/api/current_user/access_tokens/:id
Returns
Revoke token for current user
$ curl 'https://ci.example.com/go/api/current_user/access_tokens/42' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"revoke_cause": "token was compromised"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/current_user/access_tokens/:id"
}
},
"id" : 42,
"description" : "token was compromised",
"username" : "username",
"revoked" : true,
"revoke_cause" : "foo",
"revoked_by" : "jez",
"revoked_at" : "2019-02-20T11:25:03Z",
"created_at" : "2019-02-20T10:45:10Z",
"last_used_at" : null
}
Revokes a token so it cannot be reused again.
Available since v19.2.0.
HTTP Request
POST /go/api/current_user/access_tokens/:id/revoke
Returns
Get all tokens for all users
$ curl 'https://ci.example.com/go/api/admin/access_tokens?filter=all' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
}
},
"_embedded" : {
"access_tokens" : [ {
"_links" : { ... },
"id" : 42,
"description" : "dummy access token",
"username" : "username",
"revoked" : false,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : "2019-03-06T05:02:24Z",
"last_used_at" : null,
"revoked_because_user_deleted" : false
},
{
"_links" : { ... },
"id" : 43,
"description" : "another access token",
"username" : "username",
"revoked" : true,
"revoke_cause" : "revoke cause",
"revoked_by" : "username",
"revoked_at" : "2019-03-07T05:02:45Z",
"created_at" : "2019-03-06T05:02:34Z",
"last_used_at" : null,
"revoked_because_user_deleted" : false
}]
}
}
$ curl 'https://ci.example.com/go/api/admin/access_tokens' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
}
},
"_embedded" : {
"access_tokens" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/:id"
}
},
"id" : 42,
"description" : "dummy access token",
"username" : "username",
"revoked" : false,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : "2019-03-06T05:02:24Z",
"last_used_at" : null,
"revoked_because_user_deleted" : false
}]
}
}
$ curl 'https://ci.example.com/go/api/admin/access_tokens?filter=revoked' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
}
},
"_embedded" : {
"access_tokens" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/43"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/:id"
}
},
"id" : 43,
"description" : "another access token",
"username" : "username",
"revoked" : true,
"revoke_cause" : "revoke cause",
"revoked_by" : "username",
"revoked_at" : "2019-03-07T05:02:45Z",
"created_at" : "2019-03-06T05:02:34Z",
"last_used_at" : null,
"revoked_because_user_deleted" : false
} ]
}
}
Allows system administrators to list the tokens belonging to all users.
Available since v19.2.0.
HTTP Request
GET /go/api/admin/access_tokens
Returns
An array of access token objects.
The following filters are supported by the API. In case of no filter, only the active tokens will be send.
| Query String | Description |
|---|---|
| all | returns all the tokens for all the users |
| active | returns only the active tokens for all the users |
| revoked | returns only the revoked tokens for all the users |
Get one token for any user
$ curl 'https://ci.example.com/go/api/admin/access_tokens/42' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/:id"
}
},
"id" : 42,
"description" : "my first token",
"username" : "username",
"revoked" : false,
"revoke_cause" : null,
"revoked_by" : null,
"revoked_at" : null,
"created_at" : "2019-02-20T10:45:10Z",
"last_used_at" : null
}
Allows system administrators to view tokens belonging to any user.
Available since v19.2.0.
HTTP Request
GET /go/api/admin/access_tokens/:id
Returns
Revoke token for any user
$ curl 'https://ci.example.com/go/api/admin/access_tokens/42' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST \
-H 'Content-Type: application/json' \
-d '{
"revoke_cause": "token was compromised"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/42"
},
"doc" : {
"href" : "https://api.gocd.org/19.2.0/#access-token"
},
"find" : {
"href" : "https://ci.example.com/go/api/admin/access_tokens/:id"
}
},
"id" : 42,
"description" : "token was compromised",
"username" : "username",
"revoked" : true,
"revoke_cause" : "foo",
"revoked_by" : "jez",
"revoked_at" : "2019-02-20T11:25:03Z",
"created_at" : "2019-02-20T10:45:10Z",
"last_used_at" : null
}
Allows system administrators to revoke a token belonging to any user so that the token cannot be reused again.
Available since v19.2.0.
HTTP Request
POST /go/api/admin/access_tokens/:id/revoke
Returns
Agent Health
The agents API allows users to monitor if the agent is connected to the server and is authorized to perform a build.
Check agent-server connectivity
$ curl 'http://localhost:8152/health/v1/isConnectedToServer'
The above command returns a plain text response:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
OK!
This API when invoked on an agent, will indicate if the agent-server connectivity is in a state that allows agents to run builds.
Available since v17.11.0.
HTTP Request
GET /health/v1/isConnectedToServer
You may alternatively use:
GET /health/latest/isConnectedToServer
which will render the most recent version of the api.
Returns
A status code 200 along with text OK! if all the following conditions are met:
- able to establish HTTP(s) contact with the server
- is authorized by the server (by an admin, or by auto-registration)
The endpoint will return status 503 in any other cases.
Two consecutive failing pings will be treated as having failed healthcheck.
Agents
The agents API allows users with administrator role to manage agents.
The agent object
Available since v15.2.0.
| Attribute | Type | Description |
|---|---|---|
uuid |
String | The identifier of this agent. |
hostname |
String | The hostname of the agent. |
elastic_agent_id |
String | The elastic agent identifier of this agent. This attribute is only available if the agent is an elastic agent. Since v16.8.0. |
elastic_plugin_id |
String | The identifier of the elastic agent plugin that manages this agent instance. This attribute is only available if the agent is an elastic agent. Since v16.8.0. |
ip_address |
String | The IP address of the agent. |
sandbox |
String | The path where the agent will perform its builds. |
operating_system |
String | The operating system as reported by the agent. |
free_space |
Integer | The amount of free space in bytes. |
agent_config_state |
String | Whether an agent is enabled or not. Can be one of Pending, Enabled, Disabled. Since v15.3.0. |
agent_state |
String | The state an agent is in. Can be one of Idle, Building, LostContact, Missing, Building, Unknown. Since v15.3.0. |
agent_version |
String | The version of the agent. Since v20.5.0. |
agent_bootstrapper_version |
String | The version of the (installed) agent bootstrapper. Since v20.5.0. |
resources |
Array | The set of resources that this agent is tagged with. This attribute is only available if the agent is NOT an elastic agent. |
environments |
Array | The set of environments that this agent belongs to. Updated in v19.9.0. |
build_state |
String | If the agent is running a build, the state of the build on the agent. Can be one of Idle, Building, Cancelled, Unknown. Since v15.3.0. |
build_details |
Object | The build details provides information like pipeline, stage and job if the build_state of the agent is Building. Since v16.10.0. |
The Environment object
{
"name": "uat",
"origin": {
"type": "gocd",
"_links": {
"self": {
"href": "http://test.host/go/admin/config_xml"
},
"doc": {
"href": "https://api.gocd.org/19.3.0/#get-configuration"
}
}
}
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the environment. |
origin |
Object | Where the environment was defined. |
The Environment Origin object
{
"type": "gocd",
"_links": {
"self": {
"href": "http://test.host/go/admin/config_xml"
},
"doc": {
"href": "https://api.gocd.org/19.3.0/#get-configuration"
}
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The origin type of the environment:
|
Get all agents
$ curl 'https://ci.example.com/go/api/agents' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents"
},
"doc": {
"href": "https://api.gocd.org/#agents"
}
},
"_embedded": {
"agents": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
},
"doc": {
"href": "https://api.gocd.org/#agents"
},
"find": {
"href": "https://ci.example.com/go/api/agents/:uuid"
}
},
"uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
"hostname": "agent01.example.com",
"ip_address": "10.12.20.47",
"sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
"operating_system": "Mac OS X",
"free_space": 84983328768,
"agent_config_state": "Enabled",
"agent_state": "Idle",
"agent_version": "20.5.0",
"agent_bootstrapper_version": "20.5.0",
"resources": [
"java",
"linux",
"firefox"
],
"environments": [
{
"name": "perf",
"origin": {
"type": "gocd",
"_links": {
"self": {
"href": "https://ci.example.com/go/admin/config_xml"
},
"doc": {
"href": "https://api.gocd.org/#get-configuration"
}
}
}
},
{
"name": "UAT",
"origin": {
"type": "config-repo",
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/foo"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
}
}
},
{
"name": "test",
"origin": {
"type": "unknown"
}
}
],
"build_state": "Idle"
}
]
}
}
Lists all available agents, registered as well as agents that are in Pending state awaiting registration.
Updated to version v6 since v19.9.0.
Available since v14.3.0.
HTTP Request
GET /go/api/agents
Returns
An array of agent objects.
Get one agent
$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
},
"doc": {
"href": "https://api.gocd.org/#agents"
},
"find": {
"href": "https://ci.example.com/go/api/agents/:uuid"
}
},
"uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
"hostname": "ketanpkr.corporate.thoughtworks.com",
"ip_address": "10.12.20.47",
"sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
"operating_system": "Mac OS X",
"free_space": 85890146304,
"agent_config_state": "Enabled",
"agent_state": "Building",
"agent_version": "20.5.0",
"agent_bootstrapper_version": "20.5.0",
"resources": ["java", "linux", "firefox"],
"environments": [
{
"name": "perf",
"origin": {
"type": "gocd",
"_links": {
"self": {
"href": "https://ci.example.com/go/admin/config_xml"
},
"doc": {
"href": "https://api.gocd.org/#get-configuration"
}
}
}
},
{
"name": "UAT",
"origin": {
"type": "config-repo",
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/config_repos/foo"
},
"doc": {
"href": "https://api.gocd.org/#config-repos"
},
"find": {
"href": "https://ci.example.com/go/api/admin/config_repos/:id"
}
}
}
}
],
"build_state": "Building",
"build_details": {
"_links": {
"job": {
"href": "https://ci.example.com/go/tab/build/detail/up42/1/up42_stage/1/up42_job"
},
"stage": {
"href": "https://ci.example.com/go/pipelines/up42/1/up42_stage/1"
},
"pipeline": {
"href": "https://ci.example.com/go/tab/pipeline/history/up42"
}
},
"pipeline_name": "up42",
"stage_name": "up42_stage",
"job_name": "up42_job"
}
}
Gets an agent by its unique identifier (uuid)
Updated to version v6 since v19.9.0.
Available since v15.2.0.
HTTP Request
GET /go/api/agents/:uuid
Returns
An agent object.
Update an agent
$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"hostname": "agent02.example.com",
"agent_config_state": "Enabled",
"resources": ["Java","Linux"],
"environments": ["Dev"]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da"
},
"doc": {
"href": "https://api.gocd.org/#agents"
},
"find": {
"href": "https://ci.example.com/go/api/agents/:uuid"
}
},
"uuid": "adb9540a-b954-4571-9d9b-2f330739d4da",
"hostname": "agent02.example.com",
"ip_address": "10.12.20.47",
"sandbox": "/Users/ketanpadegaonkar/projects/gocd/gocd/agent",
"operating_system": "Mac OS X",
"free_space": 84834283520,
"agent_config_state": "Enabled",
"agent_state": "Idle",
"resources": ["Java","Linux"],
"environments": [
{
"name": "Dev",
"origin": {
"type": "gocd",
"_links": {
"self": {
"href": "https://ci.example.com/go/admin/config_xml"
},
"doc": {
"href": "https://api.gocd.org/#get-configuration"
}
}
}
}],
"build_state": "Idle"
}
Update some attributes of an agent.
Updated to version v6 since v19.9.0.
Available since v14.3.0.
HTTP Request
PATCH /go/api/agents/:uuid
Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.
| Attribute | Type | Description |
|---|---|---|
hostname |
String | The new hostname. |
resources |
String | Array |
A comma separated strings of resources, or an array of string resources. Updating of resources is NOT supported by elastic agents. |
environments |
String | Array |
A comma separated strings of environments, or an array of string environments. The agent will be associated to an environment only if an environment exists in GoCD for the given name, else will be ignored. |
agent_config_state |
String | Whether an agent should be enabled. In case of agents awaiting approval, setting this will approve the agents. Can be one of Enabled, Disabled. |
Returns
The updated agent object.
Delete an agent
$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"message": "Deleted 1 agent(s)."
}
Deletes an agent.
Updated to version v6 since v19.9.0.
Available since v14.3.0.
HTTP Request
DELETE /go/api/agents/:uuid
Returns
A message confirmation if the agent was deleted.
Bulk update agents
curl 'https://ci.example.com/go/api/agents' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"uuids": [
"adb9540a-b954-4571-9d9b-2f330739d4da",
"adb528b2-b954-1234-9d9b-b27ag4h568e1"
],
"operations": {
"environments": {
"add": ["Dev", "Test"],
"remove": ["Production"]
},
"resources": {
"add": ["Linux", "Firefox"],
"remove": ["Chrome"]
}
},
"agent_config_state" : "enabled"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"message": "Updated agent(s) with uuid(s): [adb9540a-b954-4571-9d9b-2f330739d4da, adb528b2-b954-1234-9d9b-b27ag4h568e1]."
}
Updates a list of agents.
Updated to version v6 since v19.9.0.
Available since v16.7.0.
HTTP Request
PATCH /go/api/agents
Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.
| Attribute | Type | Description |
|---|---|---|
operations |
Object | The bulk update operations performed on the set of agents. |
agent_config_state |
String | Whether an agent should be enabled. In case of agents awaiting approval, setting this will approve the agents. Can be one of Enabled, Disabled. |
Returns
A message confirmation if the agents were updated successfully.
The bulk update operation attributes
{
"environments": {
"add": [
"Dev",
"Test"
],
"remove": [
"Production"
]
},
"resources": {
"add": [
"Linux",
"Firefox"
],
"remove": [
"Chrome"
]
}
}
| Attribute | Type | Description |
|---|---|---|
environments |
Object | The environments update operation to be performed on the set of agents. |
resources |
Object | The resources update operation to be performed on the set of agents. Updating of resources is NOT supported by elastic agents. |
The environment update operation attributes
{
"add": [
"Dev",
"Test"
],
"remove": [
"Production"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of environments to which the specified agents needs to be added. If the said environment is present, the agent will be mapped to the same. |
remove |
Array | The list of environments from which the specified agents needs to be removed. |
The resources update operation attributes
{
"add": [
"Linux",
"Firefox"
],
"remove": [
"Chrome"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of resources that the agents needs to be tagged with. |
remove |
Array | The list of resources that the agents needs to be removed from. |
Bulk delete agents
curl 'https://ci.example.com/go/api/agents' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json' \
-H 'Content-Type: application/json' \
-X DELETE \
-d '{
"uuids": [
"adb9540a-b954-4571-9d9b-2f330739d4da",
"adb528b2-b954-1234-9d9b-b27ag4h568e1"
]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
{
"message": "Deleted 2 agent(s)."
}
Deletes a list of agents.
Updated to version v6 since v19.9.0.
Available since v16.7.0.
HTTP Request
DELETE /go/api/agents
Returns
A message confirmation if the agents were deleted.
Agent job run history
$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/job_run_history' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/19.11.0/#agent-job-run-history"
},
"self" : {
"href" : "https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/job_run_history"
},
"find" : {
"href" : "https://ci.example.com/go/api/agents/:uuid"
}
},
"uuid" : "adb9540a-b954-4571-9d9b-2f330739d4da",
"jobs" : [ {
"job_state_transitions" : [ {
"state_change_time" : "2019-11-12T00:20:56Z",
"state" : "Scheduled"
}, {
"state_change_time" : "2019-11-12T00:21:06Z",
"state" : "Assigned"
}, {
"state_change_time" : "2019-11-12T00:21:17Z",
"state" : "Preparing"
}, {
"state_change_time" : "2019-11-12T00:22:19Z",
"state" : "Building"
}, {
"state_change_time" : "2019-11-12T00:37:42Z",
"state" : "Rescheduled"
} ],
"job_name" : "jasmine",
"stage_name" : "build-non-server",
"stage_counter" : "1",
"pipeline_name" : "build-windows-PR",
"pipeline_counter" : 5282,
"result" : "Unknown",
"rerun" : false
} ],
"pagination" : {
"page_size" : 50,
"offset" : 812,
"total" : 813
}
}
Lists the jobs that have executed on an agent.
Updated to version v1 since v19.12.0.
Available since v14.3.0.
HTTP Request
GET /go/api/agents/:uuid/job_run_history
With pagination
GET /go/api/agents/:uuid/job_run_history?offset=:offset&page_size=:page_size&sort_column=:sort_column&sort_order=:sort_order
The following query string parameters are supported by the API.
| Attribute | Type | Description |
|---|---|---|
offset |
Number | The number of records to skip. |
page_size |
Number | The number of records per page of this response. Must be between 10 and 100. Defaults to 50. |
sort_column |
String | The sort order of records. Can be one of pipeline, stage, job, result, completed. Defaults to completed. |
sort_order |
String | The order of sorting of the column specified by sort_column. Can be one of ASC, DESC. Defaults to DESC. |
Returns
An array of job objects along with the job transitions.
The build details object
{
"build_details": {
"_links": {
"job": {
"href": "https://ci.example.com/go/tab/build/detail/pipelineName/pipelineCounter/stageName/stageCounter/jobName"
},
"stage": {
"href": "https://ci.example.com/go/pipelines/pipelineName/pipelineCounter/stageName/stageCounter"
},
"pipeline": {
"href": "https://ci.example.com/go/tab/pipeline/history/pipelineName"
}
},
"pipeline_name": "pipelineName",
"stage_name": "stageName",
"job_name": "jobName"
}
}
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | Name of the pipeline, whose job the agent is building. |
stage |
String | Name of the stage, whose job the agent is building. |
job |
String | Name of the job the agent is building. |
Kill running tasks
$ curl 'https://ci.example.com/go/api/agents/adb9540a-b954-4571-9d9b-2f330739d4da/kill_running_tasks' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
-H 'X-GoCD-Confirm: true' \
-X POST
The above command would return a HTTP status 202 without a response body.
When a job is cancelled, the agent tries to safely terminate all the running tasks for the job. If a running tasks fails to terminate the agent gets into a Building(Cancelled) state. Use this API to force kill all running tasks on an agent stuck in Building(Cancelled).
Available since v20.5.0.
HTTP Request
POST /go/api/agents/:uuid/kill_running_tasks
Returns
No Content
Artifacts
The artifacts API allows users to query and create artifacts of a job.
The artifact object
Available since v14.3.0.
| Attribute | Type | Description |
|---|---|---|
name |
String | The basename of the file/folder. |
url |
String | The URL to the artifact. |
type |
String | The type of the artifact. Can be one of file, folder. |
files |
Array | If the artifact is of type folder then this property will contain files/folders inside this folder. |
Get all artifacts
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName.json' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"name": "cruise-output",
"url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output",
"type": "folder",
"files": [
{
"name": "console.log",
"url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output/console.log",
"type": "file"
},
{
"name": "md5.checksum",
"url": "https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/cruise-output/md5.checksum",
"type": "file"
}
]
}
Lists all available artifacts in a job.
Available since v14.3.0.
HTTP Request
GET /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name.json
Returns
An array of artifact objects.
Get artifact file
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/to/file' \
-u 'username:password'
The above command returns the contents of the file you requested
Gets an artifact file by its path.
Available since v14.3.0.
HTTP Request
GET /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_file
Returns
An the contents of the requested file.
Get artifact directory
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/to/directory.zip' \
-u 'username:password'
The above command returns the contents of the directory you requested as a compressed zip file.
Gets an artifact directory by its path.
Available since v14.3.0.
HTTP Request
GET /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_directory.zip
Returns
One of -
- A status code
202 Acceptedto acknowledge your request to compress the contents of the requested directory. - The requested directory contents in the form of a zip file.
Create artifact
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/pkg/foobar-widgets-1.2.3.jar' \
-u 'username:password' \
-H 'Confirm:true' \
-X POST \
-F 'file=@target/dist/foobar-widgets-1.2.3.jar'
The above command uploads the file
target/dist/foobar-widgets-1.2.3.jarto the specified job at the remote pathpkg/foobar-widgets-1.2.3.jarand returns the following response:
HTTP/1.1 201 Created
Content-Type: text/plain; charset=UTF-8
File pkg/foobar-widgets-1.2.3.jar was created successfully
Uploads a local file as an artifact.
Available since v14.3.0.
HTTP Request
POST /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_file
The following form parameter must be specified
| Attribute | Type | Description |
|---|---|---|
file |
String | The contents file to be uploaded as multipart/form-data. |
Returns
An acknowledgement that the file was created.
Create multiple artifacts
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/in/destination' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-F 'zipfile=@target/dist/zip-of-files.zip'
The above command uploads the contents of the zip file
target/dist/zip-of-files.zipto the specified job at the remote directorypath/in/destination/and returns the following response:
HTTP/1.1 201 Created
Content-Type: text/plain; charset=UTF-8
File path/in/destination was created successfully
Example:
$ unzip -l /location/of/test.zip
Archive: location/of/test.zip
Length Date Time Name
--------- ---------- ----- ----
0 04-06-2018 10:28 x/
0 04-06-2018 10:29 x/y/
6 04-06-2018 10:29 x/y/z.txt
6 04-06-2018 10:29 x/y/a.txt
--------- -------
12 4 files
$ pwd
/location/of/gocd/artifacts/pipelines/PipelineName/541/StageName/1/JobName
$ ls
cruise-output/
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/path/in/destination' \
... \
-F 'zipfile=@/location/of/test.zip'
$ ls
cruise-output/ path/
$ find path
path
path/in
path/in/destination
path/in/destination/x
path/in/destination/x/y
path/in/destination/x/y/z.txt
path/in/destination/x/y/a.txt
Uploads local files as artifacts to the GoCD server. This is done by creating a zip file of the files which need to be uploaded. The GoCD server will unzip the files, once it is uploaded, allowing multiple files to be uploaded at a time.
Available since v14.3.0.
HTTP Request
POST /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_directory
The following form parameter must be specified
| Attribute | Type | Description |
|---|---|---|
zipfile |
String | The zip file to be uploaded as multipart/form-data. |
Returns
An acknowledgement that the directory was created.
Append to artifact
$ curl 'https://ci.example.com/go/files/PipelineName/541/StageName/1/JobName/logs/operations.log' \
-u 'username:password' \
-T logs/production.log
The above command appends the file
logs/production.logto the specified job at the remote pathlogs/operations.logand returns the following response:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
File logs/operations.log was appended successfully
Appends a local file to an existing artifact.
Available since v14.3.0.
HTTP Request
PUT /go/files/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/*path_to_file
Returns
An acknowledgement that the file was appended to.
Backups
The backups API allows users with administrator role to manage GoCD server backups.
The Backup Object
Available since v19.3.0.
| Attribute | Type | Description |
|---|---|---|
time |
DateTime | The time of the backup. |
path |
String | The filesystem location where the backed up files are stored. |
user |
Object | The user that performed this backup. |
status |
String | Status of the backup. Possible values are COMPLETED, IN_PROGRESS, ERROR, ABORTED. |
progress_status |
String | If the status of the backup is IN_PROGRESS, then this field gives more granular details about the back up in progress. Possible values are STARTING, CREATING_DIR, BACKUP_VERSION_FILE, BACKUP_CONFIG, BACKUP_CONFIG_REPO, BACKUP_DATABASE, POST_BACKUP_SCRIPT_START, POST_BACKUP_SCRIPT_COMPLETE. |
message |
String | The detailed message corresponding to the ‘status’ or ‘progress_status’ fields. |
Schedule Backup
$ curl 'https://ci.example.com/go/api/backups' \
-i \
-u 'username:password' \
-H 'X-GoCD-Confirm: true' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X POST
The above command returns an empty response body with a response code of 202 (Accepted) to indicate that request to backup is accepted and is scheduled asynchronously. It returns location header in the response that can be used for polling the status of the backup.
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json;charset=utf-8
Location: /go/api/backups/:backup_id
Retry-After: 5
$ curl 'https://ci.example.com/go/api/backups/:backup_id' \
-i \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X GET
The above command is used to poll the status of the backup that was scheduled previously. It returns JSON structured like this:
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#backups"
}
},
"time": "2015-08-07T10:07:19.868Z",
"path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
"status" : "COMPLETED",
"progress_status" : "BACKUP_DATABASE",
"message" : "Backup was generated successfully.",
"user": {
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/username"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
},
"current_user" : {
"href" : "https://ci.example.com/go/api/users/current_user"
}
},
"login_name": "username"
}
}
Available since v19.3.0.
HTTP Request
POST /go/api/backups
Returns an empty response body with a response code 202 (Accepted) and location header containing the link to be polled for checking the status of the backup.
Get Backup
$ curl 'https://ci.example.com/go/api/backups/:backup_id' \
-i \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X GET
The above command is used to poll the status of the backup that was scheduled previously. It returns JSON structured like this:
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#backups"
}
},
"time": "2015-08-07T10:07:19.868Z",
"path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
"status" : "COMPLETED",
"progress_status" : "BACKUP_DATABASE",
"message" : "Backup was generated successfully.",
"user": {
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/username"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
},
"current_user" : {
"href" : "https://ci.example.com/go/api/users/current_user"
}
},
"login_name": "username"
}
}
Available since v19.3.0.
GET /go/api/backups/:backup_id
Returns
A new backup object.
Current User
The current user API allows any authenticated user to manage certain aspects of their profile.
Get current user
$ curl 'https://ci.example.com/go/api/current_user' \
-u 'jdoe:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/jdoe"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "John Doe",
"enabled": true,
"email": null,
"email_me": false,
"checkin_aliases": [
]
}
Gets the current user
Available since v17.5.0.
HTTP Request
GET /go/api/current_user
Returns
A user object.
Update current user
$ curl 'https://ci.example.com/go/api/current_user' \
-u 'jdoe:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"email": "jdoe@example.com",
"email_me": true,
"checkin_aliases": ["jdoe", "johndoe"]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/jdoe"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "jdoe",
"enabled": false,
"email": "jdoe@example.com",
"email_me": true,
"checkin_aliases": [
"jdoe",
"johndoe"
]
}
Update some attributes of the current user.
Available since v17.5.0.
HTTP Request
PATCH /go/api/current_user
Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.
| Attribute | Type | Description |
|---|---|---|
email |
String | The user’s email address. |
email_me |
Boolean | Boolean indicating if the user should be signed up for email notifications. |
checkin_aliases |
Array | A list of SCM checkin aliases to map users to SCM commits. |
Returns
The updated user object.
Dashboard
The Dashboard API allows users to view dashboard information.
Dashboard object
Available since v18.12.0.
| Attribute | Type | Description |
|---|---|---|
pipelines |
Object | The list of pipelines. |
environments |
Object | The list of environments. |
pipeline_groups |
Object | The list of dashboard pipeline groups. |
Dashboard pipeline object
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the pipeline. |
last_updated_timestamp |
Number | The dashboard pipeline instance’s last updated timestamp. |
locked |
Boolean | Whether the current pipeline instance is locked. |
pause_info |
Object | The pause information of the pipeline. |
can_operate |
Boolean | Whether the current user has permission to trigger the pipeline. |
can_administer |
Boolean | Whether the current user has permission to edit the pipeline configurations. |
can_unlock |
Boolean | Whether the current user has permission to unlock a locked pipeline isntance. |
can_pause |
Boolean | Whether the current user has permission to pause the pipeline. |
from_config_repo |
Boolean | Whether the pipeline’s configuration is defined using pipeline as code. |
instances |
Object | The list of pipeline instances. |
Dashboard pipeline pause information object
{
"pause_info": {
"paused": true,
"paused_by": "John",
"pause_reason": "Pipeline Under Maintenance",
"paused_at": "2019-03-01T06:43:38Z"
}
}
| Attribute | Type | Description |
|---|---|---|
paused |
Boolean | Whether the current pipeline instance is paused. |
paused_by |
String | The name of the user who paused the pipeline. |
pause_reason |
String | The pause cause of the pipeline. |
paused_at |
String | The pipeline paused at time. |
Dashboard pipeline pipeline-instance object
{
"instances": [
{
"label": "1",
"counter": 1,
"triggered_by": "Triggered by changes",
"scheduled_at": "2018-11-21T09:43:07Z",
"_embedded": {
"stages": [
{
"name": "up42_stage",
"counter": "1",
"status": "Building",
"approved_by": "changes",
"scheduled_at": "2018-11-21T09:43:07Z"
}
]
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
label |
String | The label of the current pipeline instance. |
counter |
Number | The pipeline counter of the current pipeline instance. |
triggered_by |
String | The name of the user who triggered the current pipeline instance. |
scheduled_at |
Date | The schedule time of the current pipeline instance. |
stages |
Object | The list of stages of the current pipeline instance. |
Dashboard pipeline’s stage object
{
"stages": [
{
"name": "up42_stage",
"counter": "1",
"status": "Cancelled",
"approved_by": "changes",
"cancelled_by": "bob",
"scheduled_at": "2018-11-21T09:43:07Z"
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the stage. |
counter |
Number | The stage counter of the current stage instance. |
status |
String | The status of the current stage instance. Can be one of Building, Cancelled, Passed, Failed. |
approved_by |
String | The approver of the current stage instance. |
cancelled_by |
String | Indicates who cancelled the stage if stage status is Cancelled. |
scheduled_at |
Date | The schedule time of the current stage instance. |
Dashboard environment object
{
"environments": [
{
"name": "QA",
"pipelines": [
"up42"
],
"can_administer": true
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the environment. |
pipelines |
Object | The list of pipelines which belongs to the current environment. |
can_administer |
Boolean | Whether the current has permission to edit the environment configurations. |
Dashboard Pipeline Group object
{
"pipeline_groups": [
{
"name": "UAT",
"pipelines": [
"up42"
],
"can_administer": true
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the pipeline group. |
pipelines |
Object | The list of pipelines which belongs to the current pipeline group. |
can_administer |
Boolean | Whether the current user have permissions to edit the pipeline group configurations. |
Get Dashboard
$ curl 'https://ci.example.com/go/api/dashboard' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v4+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v4+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/dashboard"
},
"doc" : {
"href" : "https://api.go.cd/current/#dashboard"
}
},
"_personalization" : "2356e5d4241f22987d8f8cb8920913fda237385b423bd7eec7e97b2a9eb1be1a",
"_embedded" : {
"pipeline_groups" : [ {
"_links" : {
"doc" : {
"href" : "https://api.go.cd/current/#pipeline-groups"
},
"self" : {
"href" : "https://ci.example.com/go/api/config/pipeline_groups"
}
},
"name" : "first",
"pipelines" : [ "up42" ],
"can_administer" : true
} ],
"environments" : [ {
"_links" : {
"doc" : {
"href" : "https://api.gocd.org/current/#environment-config"
},
"self" : {
"href" : "https://ci.example.com/go/api/admin/environments/asd"
}
},
"name" : "asd",
"pipelines" : [ "up42" ],
"can_administer" : true
} ],
"pipelines" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/pipelines/up42/history"
},
"doc" : {
"href" : "https://api.go.cd/current/#pipelines"
}
},
"name" : "up42",
"last_updated_timestamp" : 1542863609039,
"locked" : false,
"pause_info" : {
"paused" : false,
"paused_by" : null,
"pause_reason" : null
},
"can_operate" : true,
"can_administer" : true,
"can_unlock" : true,
"can_pause" : true,
"from_config_repo" : false,
"_embedded" : {
"instances" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/pipelines/up42/instance/1"
}
},
"label" : "1",
"counter" : 1,
"triggered_by" : "Triggered by changes",
"scheduled_at" : "2018-11-21T09:43:07Z",
"_embedded" : {
"stages" : [ {
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/stages/up42/1/up42_stage/1"
}
},
"name" : "up42_stage",
"counter" : "1",
"status" : "Building",
"approved_by" : "changes",
"scheduled_at" : "2018-11-21T09:43:07Z"
} ]
}
} ]
}
} ]
}
}
Lists pipelines on Dashboard along with pipeline groups and environments information.
Available since v18.12.0.
HTTP Request
GET /go/api/dashboard
Returns
An array of pipelines on Dashboard.
Encryption
The encryption API allows users with any administrator privilege to get the cipher text(encrypted text) corresponding to any plain text value. You may use this cipher text in other APIs that allow you to configure the pipelines and templates.
Encrypt a plain text value
$ curl 'https://ci.example.com/go/api/admin/encrypt' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"value": "badger"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "http://ci.example.com/go/api/admin/encrypt"
},
"doc": {
"href": "https://api.gocd.org/#encryption"
}
},
"encrypted_value": "aSdiFgRRZ6A="
}
Returns the encrypted value for the plain text passed.
Available since v17.1.0.
HTTP Request
POST /go/api/admin/encrypt
Returns
The encrypted value of the plain text.
Feeds
The feed API allows users to view feed information.
Get all pipelines
$ curl 'https://ci.example.com/go/api/feed/pipelines.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<pipelines>
<link rel="self" href="https://build.gocd.org/go/api/feed/pipelines.xml" />
<pipeline href="https://build.gocd.org/go/api/feed/pipelines/build-linux/stages.xml" />
<pipeline href="https://build.gocd.org/go/api/feed/pipelines/build-windows/stages.xml" />
<pipeline href="https://build.gocd.org/go/api/feed/pipelines/plugins/stages.xml" />
</pipelines>
Lists all pipelines.
Updated to newer version since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/feed/pipelines.xml
Returns
An array of pipelines.
Get feed of all stages in a pipeline
$ curl 'https://ci.example.com/go/api/feed/pipelines/mypipeline/stages.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:go="http://www.thoughtworks-studios.com/ns/go">
<title><![CDATA[mypipeline]]></title>
<id>https://ci.example.com/go/api/feed/pipelines/mypipeline/stages.xml</id>
<author>
<name>Go</name>
</author>
<updated>2020-01-11T13:09:57Z</updated>
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/stages.xml"/>
<link rel="next" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/stages.xml?before=4672"/>
<entry>
<title><![CDATA[mypipeline(4684) stage defaultStage(1) Cancelled]]></title>
<updated>2020-01-11T13:09:57Z</updated>
<id>https://ci.example.com/go/pipelines/mypipeline/4684/defaultStage/1</id>
<author>
<name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
</author>
<link rel="alternate" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4684/defaultStage/1.xml" title="defaultStage Stage Detail" type="application/vnd.go+xml"/>
<link rel="alternate" href="https://ci.example.com/go/pipelines/mypipeline/4684/defaultStage/1" title="defaultStage Stage Detail" type="text/html"/>
<link rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4684.xml" title="mypipeline Pipeline Detail" type="application/vnd.go+xml"/>
<link rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" href="https://ci.example.com/go/pipelines/mypipeline/4684/defaultStage/1" title="mypipeline Pipeline Detail" type="text/html"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="stage" label="Stage"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="completed" label="Completed"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="passed" label="Passed"/>
</entry>
<entry>
<title><![CDATA[mypipeline(4683) stage build-server(1) Failed]]></title>
<updated>2020-01-11T13:46:02Z</updated>
<id>https://ci.example.com/go/pipelines/mypipeline/4683/build-server/1</id>
<author>
<name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
</author>
<link rel="alternate" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/build-server/1.xml" title="build-server Stage Detail" type="application/vnd.go+xml"/>
<link rel="alternate" href="https://ci.example.com/go/pipelines/mypipeline/4683/build-server/1" title="build-server Stage Detail" type="text/html"/>
<link rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683.xml" title="mypipeline Pipeline Detail" type="application/vnd.go+xml"/>
<link rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" href="https://ci.example.com/go/pipelines/mypipeline/4683/build-server/1" title="mypipeline Pipeline Detail" type="text/html"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="stage" label="Stage"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="completed" label="Completed"/>
<category scheme="http://www.thoughtworks-studios.com/ns/categories/go" term="failed" label="Failed"/>
</entry>
</feed>
Gets feed of all stages for the specified pipeline with links to the pipeline and stage details.
Updated to newer version since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/feed/pipelines/:pipeline_name/stages.xml
Returns
An array of feed of stages.
Get pipeline
$ curl 'https://ci.example.com/go/api/pipelines/mypipeline/1.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<pipeline name="mypipeline" counter="4683">
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:4683]]></id>
<scheduleTime>2020-01-11T13:02:39Z</scheduleTime>
<link rel="insertedAfter" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/120064.xml"/>
<materials>
<material>
<material materialUri="https://ci.example.com/go/api/feed/materials/mypipeline/4683/2724d1969830c35097dcfd76b712d0a63d1cd636c8c9793ee1c3922421841d4a.xml" type="GitMaterial" url="https://git.gocd.io/git/gocd/gocd" branch="master" shallowClone="true">
<modifications>
<changeset>
<user><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></user>
<checkinTime>2020-01-11T12:45:32Z</checkinTime>
<revision><![CDATA[6e6a8e2e174c708b1f3f4dd798b90c2cc5f1bb49]]></revision>
<message><![CDATA[Updated readme]]></message>
<file name="server/src/main/webapp/WEB-INF/rails/package.json" action="modified"/>
<file name="server/src/main/webapp/WEB-INF/rails/yarn.lock" action="modified"/>
</changeset>
</modifications>
</material>
</material>
</materials>
<stages>
<stage href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/build-non-server/1.xml"/>
<stage href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/build-server/2.xml"/>
</stages>
<approvedBy><![CDATA[changes]]></approvedBy>
</pipeline>
Gets XML representation of pipeline.
Updated to newer version since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/:pipeline_counter.xml
Returns
A xml representation of pipeline run.
Get stage
$ curl 'https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<stage name="defaultStage" counter="1">
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:stage-id:mypipeline:4683:defaultStage:1]]></id>
<pipeline name="defaultStage" counter="4683" label="4683" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683.xml"/>
<updated>2020-01-11T13:09:57Z</updated>
<result>Passed</result>
<state>Completed</state>
<approvedBy><![CDATA[admin]]></approvedBy>
<jobs>
<job href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1/defaultJob.xml"/>
</jobs>
</stage>
Gets XML representation of stage.
Updated to newer version since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/feed/pipelines/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter.xml
Returns
A xml representation of stage run.
Get job
$ curl 'https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1/defaultJob.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<job name="defaultJob">
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1/defaultJob.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:4683:defaultStage:1:defaultJob]]></id>
<pipeline name="mypipeline" counter="4683" label="4683"/>
<stage name="defaultStage" counter="1" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/4683/defaultStage/1.xml"/>
<result>Passed</result>
<state>Completed</state>
<agent uuid="3787ca03-e8b1-4237-8e81-338b1e3eb9b7"/>
<!--Artifacts of type `file` will not be shown. See https://github.com/gocd/gocd/pull/2875-->
<artifacts baseUri="https://ci.example.com/go/files/mypipeline/4683/defaultStage/1/defaultJob" pathFromArtifactRoot="pipelines/mypipeline/4683/defaultStage/1/defaultJob"/>
<!--Resources are now intentionally left blank. See https://github.com/gocd/gocd/pull/2875-->
<resources/>
<!--Environment variables are now intentionally left blank. See https://github.com/gocd/gocd/pull/2875-->
<environmentVariables/>
</job>
Gets XML representation of job.
Updated to newer version since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/feed/pipelines/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name.xml
Returns
A xml representation of job run.
Get material
$ curl 'https://ci.example.com/go/api/feed/materials/pipelines/4683/2724d1969830c35097dcfd76b712d0a63d1cd636c8c9793ee1c3922421841d4a.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<material materialUri="https://ci.example.com/go/api/feed/materials/mypipeline/4683/2724d1969830c35097dcfd76b712d0a63d1cd636c8c9793ee1c3922421841d4a.xml"
type="GitMaterial" url="https://git.gocd.io/git/gocd/gocd" branch="master" shallowClone="true">
<modifications>
<changeset>
<user><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></user>
<checkinTime>2020-01-11T12:45:32Z</checkinTime>
<revision><![CDATA[6e6a8e2e174c708b1f3f4dd798b90c2cc5f1bb49]]></revision>
<message><![CDATA[Updated readme.md]]></message>
<file name="readme.md" action="modified"/>
</changeset>
</modifications>
</material>
Gets XML representation of job.
Available since v20.1.0.
HTTP Request
GET /go/api/feed/materials/:pipeline_name/:pipeline_counter/:pipeline_unique_fingerprint.xml
Returns
A xml representation of material.
Scheduled jobs
$ curl 'https://ci.example.com/go/api/feed/jobs/scheduled.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<?xml version="1.0" encoding="UTF-8"?>
<scheduledJobs>
<job name="job1" id="6">
<link rel="self" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job1"/>
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/5/defaultStage/1/job1.xml"/>
<link rel="alternate" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job1" title="job1 Job Detail" type="text/html"/>
<buildLocator>mypipeline/5/defaultStage/1/job1</buildLocator>
</job>
<job name="job2" id="7">
<link rel="self" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job2"/>
<link rel="self" href="https://ci.example.com/go/api/feed/pipelines/mypipeline/5/defaultStage/1/job2.xml"/>
<link rel="alternate" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job2" title="job2 Job Detail" type="text/html"/>
<buildLocator>mypipeline/5/defaultStage/1/job2</buildLocator>
</job>
</scheduledJobs>
Lists all the current job instances which are scheduled but not yet assigned to any agent.
Available since v20.6.0.
HTTP Request
GET /go/api/feed/jobs/scheduled.xml
Returns
An array of scheduled job instances.
Jobs
The jobs API allows users to view job information.
Get job instance
$ curl 'https://ci.example.com/go/api/jobs/myPipeline/1/myStages/1/myJob' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json;charset=utf-8
{
"name" : "myJob",
"state" : "Completed",
"result" : "Passed",
"original_job_id" : null,
"scheduled_date": 1436519914378,
"rerun" : false,
"agent_uuid" : "b74d88d-d8823765f63c",
"pipeline_name" : "myPipeline",
"pipeline_counter" : 1,
"stage_name" : "myStages",
"stage_counter" : "1",
"job_state_transitions" : [
{
"state": "Scheduled",
"state_change_time": 1578891141997
},
{
"state": "Assigned",
"state_change_time": 1436509524491
},
{
"state": "Preparing",
"state_change_time": 1436509534639
},
{
"state": "Building",
"state_change_time": 1436509542522
},
{
"state": "Completing",
"state_change_time": 1436509642582
},
{
"state": "Completed",
"state_change_time": 1436509642631
}
]
}
Gets job instance object.
Available since v20.1.0.
HTTP Request
GET /go/api/jobs/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name
Returns
A job instance object.
Responses include job_state_transitions since v22.2.0.
Get job history
$ curl 'https://ci.example.com/go/api/jobs/mypipeline/defaultStage/job1/history' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"jobs": [
{
"name": "job1",
"agent_uuid": null,
"scheduled_date": 1436519914378,
"original_job_id": null,
"pipeline_counter": 5,
"rerun": false,
"pipeline_name": "mypipeline",
"result": "Unknown",
"state": "Scheduled",
"stage_counter": "1",
"stage_name": "defaultStage",
},
{
"name": "job1",
"agent_uuid": "278fb0b6-d3b8-47e1-9443-67f26bfb5c15",
"scheduled_date": 1436519733253,
"original_job_id": null,
"pipeline_counter": 4,
"rerun": false,
"pipeline_name": "mypipeline",
"result": "Passed",
"state": "Completed",
"stage_counter": "1",
"stage_name": "defaultStage",
}
]
}
The job history allows users to list job instances of specified job. Supports cursor based pagination. The json output provides the next link which needs to be followed for the next set of records (if present). It also provides a previous which can be followed to get the previous page (if there is one).
The API supports the following query params:
| Param Name | Description |
|---|---|
page_size |
The number of records per page. Can be between 10 and 100. Defaults to 10 |
after |
The cursor value for fetching the next set of records |
before |
The cursor value for fetching the previous set of records |
Available since v14.3.0.
Updated to version v1 since v20.1.0.
HTTP Request
GET /go/api/jobs/:pipeline_name/:stage_name/:job_name/history
Returns
An array of jobs instances.
Maintenance Mode
The GoCD Server Maintenance mode API allows admin users to manage GoCD server maintenance mode.
The Maintenance Mode Info Object
Available since v19.1.0.
| Attribute | Type | Description |
|---|---|---|
is_maintenance_mode |
Boolean | Whether the GoCD server is in maintenance mode or not. |
metadata |
Object | The GoCD server maintenance mode state metadata. |
attributes |
Object | The GoCD server maintenance mode state attributes. |
Maintenance Mode Metadata
{
"metadata": {
"updated_by": "John",
"updated_on": "2018-12-31T10:52:25Z"
}
}
| Attribute | Type | Description |
|---|---|---|
updated_by |
String | The administrator who updated maintenance mode state. |
updated_on |
Timestamp | The maintenance mode state last updated time. |
Maintenance Mode Attributes
{
"attributes": {
"has_running_systems": false,
"running_systems": {
"material_update_in_progress": [
{
"type": "hg",
"mdu_start_time": "2018-12-10T04:19:31Z",
"attributes": {
"url": "https://bdpiparva@bitbucket.org/foo/bar-mercurial",
"name": "Foobar",
"auto_update": true,
"invert_filter": false
}
}
],
"building_jobs": [
{
"pipeline_name": "up42",
"pipeline_counter": 5,
"stage_name": "up42_stage",
"stage_counter": "1",
"name": "up42_job",
"state": "Building",
"scheduled_date": "2018-12-31T10:57:17Z",
"agent_uuid": "agent-uuid-1"
}
],
"scheduled_jobs": [
{
"pipeline_name": "up42",
"pipeline_counter": 5,
"stage_name": "up42_stage",
"stage_counter": "1",
"name": "up42_job_2",
"state": "Scheduled",
"scheduled_date": "2018-12-31T10:57:17Z",
"agent_uuid": null
}
]
}
}
}
| Attribute | Type | Description |
|---|---|---|
has_running_systems |
Boolean | Whether there are any running subsystems in GoCD. |
running_systems |
Object | GoCD running sub-systems. |
Maintenance Mode Attributes Running Systems
{
"running_systems": {
"material_update_in_progress": [
{
"type": "hg",
"mdu_start_time": "2018-12-10T04:19:31Z",
"attributes": {
"url": "https://bdpiparva@bitbucket.org/foo/bar-mercurial",
"name": "Foobar",
"auto_update": true,
"invert_filter": false
}
}
],
"building_jobs": [
{
"pipeline_name": "up42",
"pipeline_counter": 5,
"stage_name": "up42_stage",
"stage_counter": "1",
"name": "up42_job",
"state": "Building",
"scheduled_date": "2018-12-31T10:57:17Z",
"agent_uuid": "agent-uuid-1"
}
],
"scheduled_jobs": [
{
"pipeline_name": "up42",
"pipeline_counter": 5,
"stage_name": "up42_stage",
"stage_counter": "1",
"name": "up42_job_2",
"state": "Scheduled",
"scheduled_date": "2018-12-31T10:57:17Z",
"agent_uuid": null
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
material_update_in_progress |
Array | The list of materials currently peforming MDU. |
building_jobs |
Array | The list of currently building jobs. Building Jobs are the jobs which are currently running on an agent. |
scheduled_jobs |
Array | The list of currently scheduled jobs. Scheduled Jobs are the jobs which are waiting for an agent to run on. |
Maintenance Mode Attributes Running Job
{
"pipeline_name": "up42",
"pipeline_counter": 5,
"stage_name": "up42_stage",
"stage_counter": "1",
"name": "up42_job",
"state": "Scheduled",
"scheduled_date": "2018-12-31T10:57:17Z",
"agent_uuid": "agent-uuid-1"
}
| Attribute | Type | Description |
|---|---|---|
pipeline_name |
String | The name of the pipeline. |
pipeline_counter |
Integer | The running pipeline instance counter. |
stage_name |
String | The name of the stage. |
stage_counter |
Integer | The running stage instance counter. |
name |
String | The name of the job. |
state |
String | The state of the running job. one_of: %w(Scheduled, Assigned, Preparing, Building, Completing, Completed, Rescheduled). |
scheduled_date |
Timestamp | The job scheduled date. |
agent_uuid |
String | The uuid of the agent on whichb the current job is running. |
Enable Maintenance Mode
$ curl 'https://ci.example.com/go/api/admin/maintenance_mode/enable' \
-X POST \
-u 'username:password' \
-H 'X-GoCD-Confirm:true' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 204 No Content
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
Enables GoCD server maintenance mode.
Available since v19.1.0.
HTTP Request
GET /go/api/admin/maintenance_mode/enable
Returns
No Content
Disable Maintenance Mode
$ curl 'https://ci.example.com/go/api/admin/maintenance_mode/disable' \
-X POST \
-u 'username:password' \
-H 'X-GoCD-Confirm:true' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 204 No Content
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
Disables GoCD server maintenance mode.
Available since v19.1.0.
HTTP Request
GET /go/api/admin/maintenance_mode/disable
Returns
No Content
Get Maintenance Mode Info
$ curl 'https://ci.example.com/go/api/admin/maintenance_mode/info' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
ETag: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"
{
"_links" : {
"self" : {
"href" : "https://ci.example.com/go/api/admin/maintenance_mode/info"
},
"doc" : {
"href" : "https://api.gocd.org/current/#maintenance-mode-info"
}
},
"_embedded" : {
"is_maintenance_mode" : true,
"metadata" : {
"updated_by" : "admin",
"updated_on" : "2019-01-02T04:18:28Z"
},
"attributes" : {
"has_running_systems" : false,
"running_systems" : {
"material_update_in_progress" : [ ],
"scheduled_jobs" : [ ],
"running_jobs" : [ ]
}
}
}
}
Gets the server maintenance mode information.
Available since v19.1.0.
HTTP Request
GET /go/api/admin/maintenance_mode/info
Returns
A maintenance mode info object.
Notify Materials
The materials API allows users to notify materials in the GoCD configuration.
Notify SVN materials
$ curl 'https://ci.example.com/go/api/admin/materials/svn/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X POST \
-d '{"repository_url": "http://svn.example.com/test-repo"}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=UTF-8
{"message": "The material is now scheduled for an update. Please check relevant pipeline(s) for status."}
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
POST /go/api/admin/materials/svn/notify
One of the following properties must be specified in the json payload.
| Attribute | Type | Description |
|---|---|---|
repository_url |
String | The svn repository url as defined in cruise-config.xml or a Config Repo. |
uuid |
String | The subversion repository UUID. |
Returns
A confirmation message.
Notification script
To notify GoCD via a SVN post commit hook, you may use the following post commit hook in your subversion repository.
The post commit hook is located at /path/to/repository/hooks/post-commit.
#!/bin/sh
curl 'https://ci.example.com/go/api/admin/materials/svn/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json'
-X POST \
-d '{"repository_url": "http://svn.example.com/test-repo"}'
# -- or using UUID --
REPOS="$1"
REV="$2"
UUID=$(svnlook uuid $1)
curl 'https://ci.example.com/go/api/material/svn/notify' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d '{"uuid": "$UUID"}'
Notify Git materials
$ curl 'https://ci.example.com/go/api/admin/materials/git/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{"repository_url": "git://git.example.com/git/funky-widgets.git"}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json; charset=UTF-8
{"message": "The material is now scheduled for an update. Please check relevant pipeline(s) for status."}
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
POST /go/api/admin/materials/git/notify
The following json payload must be specified.
| Attribute | Type | Description |
|---|---|---|
repository_url |
String | The git repository url as defined in cruise-config.xml or a Config Repo. |
Returns
A confirmation message.
Notification script
To notify GoCD via a Git post commit hook, you may use the following post commit hook in your git repository.
The post commit hook is located at /path/to/repository.git/hooks/post-receive.
#!/bin/sh
curl 'https://ci.example.com/go/api/admin/materials/git/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{"repository_url": "git://git.example.com/git/funky-widgets.git"}'
Notify Mercurial materials
$ curl 'https://ci.example.com/go/api/admin/materials/hg/notify' \
-u 'username:password' \
-H 'Accept: ' \
-H 'Content-Type: application/json %>' \
-X POST \
-d '{"repository_url": "ssh://hg.example.com/hg/repos/funky-widgets"}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json; charset=UTF-8
{"message": "The material is now scheduled for an update. Please check relevant pipeline(s) for status."}
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
POST /go/api/admin/materials/hg/notify
The following json payload must be specified.
| Attribute | Type | Description |
|---|---|---|
repository_url |
String | The Mercurial repository URL as defined in cruise-config.xml or a Config Repo. |
Returns
A confirmation message.
Notification script
To notify GoCD via a Mercurial changegroup hook, you may use the following in your Mercurial repository.
The hook goes into the hgrc file, located at /path/to/hg/repository/.hg/hgrc.
[hooks]
changegroup = curl -sSL 'https://ci.example.com/go/api/admin/materials/hg/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{"repository_url": "ssh://hg.example.com/hg/repos/funky-widgets"}'
Notify other SCM materials
$ curl 'https://ci.example.com/go/api/admin/materials/scm/notify' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{"scm_name": "material_name"}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json; charset=UTF-8
{"message": "The material is now scheduled for an update. Please check relevant pipeline(s) for status."}
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Updated to version v2 since v19.10.0.
Available since v14.3.0.
HTTP Request
POST /go/api/admin/materials/scm/notify
The following json payload must be specified.
| Attribute | Type | Description |
|---|---|---|
scm_name |
String | The scm_name is the material name as defined in pipeline material page. |
Returns
A confirmation message.
Webhook
The webhook API allows users to notify GoCD in case of a push in the relevant repository.
Hosting on BitBucket Server
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Available since v19.3.0.
To notify GoCD of an push to a self-Hosted BitBucket Server repository via a group or project webhook, configure BitBucket to use the webhook API negating the need for basic authentication on each request.
https://gocd.example.com:8154/go/api/webhooks/hosted_bitbucket/notify
To secure the http endpoint, the webhook configuration on BitBucket Server must specify a Secret, the value of the Secret should be the same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.
Updated in v20.9.0
Added support to trigger one or more pluggable SCMs via SCM_NAME query param.
https://gocd.example.com:8154/go/api/webhooks/hosted_bitbucket/notify?SCM_NAME=scm1&SCM_NAME=scm2
Returns
A text confirmation, with the http status 202 Accepted.
Hosting on BitBucket Cloud
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Available since v17.11.0.
To notify GoCD of an push to a BitBucket Cloud repository via a group or project webhook, configure BitBucket to use the webhook API negating the need for basic authentication on each request.
https://{webhookSecret}:x@gocd.example.com:8154/go/api/webhooks/bitbucket/notify
To secure the http endpoint, the webhook configuration on BitBucket must specify a Basic Authentication User, the value of the Basic Authentication User should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.
Updated in 20.9.0
Added support to trigger one or more pluggable SCMs via SCM_NAME query param.
https://{webhookSecret}:x@gocd.example.com:8154/go/api/webhooks/bitbucket/notify?SCM_NAME=scm1&SCM_NAME=scm2
Returns
A text confirmation, with the http status 202 Accepted.
Hosting on GitHub or GitHub Enterprise
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Available since v17.6.0.
To notify GoCD of a push to a GitHub repository via a repository or organization webhook, configure GitHub to use the webhook API negating the need for basic authentication on each request.
https://gocd.example.com:8154/go/api/webhooks/github/notify
To secure the http endpoint, the webhook configuration on GitHub must specify a Secret, the value of the Secret should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.
Updated in v20.9.0
Added support to trigger one or more pluggable SCMs via SCM_NAME query param.
https://gocd.example.com:8154/go/api/webhooks/github/notify?SCM_NAME=scm1&SCM_NAME=scm2
Returns
A text confirmation, with the http status 202 Accepted.
Hosting on GitLab
API that notifies GoCD Server when a commit/push has been made in version control and GoCD needs to trigger relevant pipelines.
Available since v17.11.0.
To notify GoCD of an push to a GitLab repository via a group or project webhook, configure GitLab to use the webhook API negating the need for basic authentication on each request.
https://gocd.example.com:8154/go/api/webhooks/gitlab/notify
To secure the http endpoint, the webhook configuration on GitLab must specify a Secret Token, the value of the Secret Token should be same as the value of the webhookSecret attribute on the <server/> element in the file cruise-config.xml. Do not specify any basic authentication credentials in the webhook URL.
Updated in v20.9.0
Added support to trigger one or more pluggable SCMs via SCM_NAME query param.
https://gocd.example.com:8154/go/api/webhooks/gitlab/notify?SCM_NAME=scm1&SCM_NAME=scm2
Returns
A text confirmation, with the http status 202 Accepted.
Pipeline Instances
The Pipeline Instances API allows users to view Pipeline Instance information.
Get pipeline instance
$ curl 'http://ci.example.com/go/api/pipelines/PipelineName/1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"name" : "PipelineName",
"counter" : 1,
"label" : "1",
"natural_order" : 1.0,
"can_run" : true,
"preparing_to_schedule" : false,
"comment" : null,
"scheduled_date" : 1436519914578,
"build_cause" : {
"trigger_message" : "modified by user <user@users.noreply.github.com>",
"trigger_forced" : false,
"approver" : "",
"material_revisions" : [ {
"changed" : true,
"material" : {
"name" : "https://github.com/gocd/gocd",
"fingerprint" : "de08b34d116a1c0cf57cd76683bf21",
"type" : "Git",
"description" : "URL: https://github.com/gocd/gocd, Branch: master"
},
"modifications" : [ {
"revision" : "40f0a7ef224a0a2fba438b158483b",
"modified_time" : 1436519914378,
"user_name" : "user <user@users.noreply.github.com>",
"comment" : "some commit message.",
"email_address" : null
} ]
} ]
},
"stages" : [ {
"result" : "Passed",
"status" : "Passed",
"rerun_of_counter" : null,
"name" : "stage",
"counter" : "1",
"scheduled" : true,
"approval_type" : "success",
"approved_by" : "changes",
"operate_permission" : true,
"can_run" : true,
"jobs" : [ {
"name" : "job",
"scheduled_date" : 1436782534378,
"state" : "Completed",
"result" : "Passed"
} ]
} ]
}
Gets pipeline instance object.
Updated to version v1 since v20.1.0.
Available since v15.1.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/:pipeline_counter
Returns
A pipeline instance object.
Get pipeline history
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/history' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"next": {
"href": "http://ci.example.com/go/api/pipelines/pipeline1/history?after=35"
},
"previous": {
"href": "http://ci.example.com/go/api/pipelines/pipeline1/history?before=9"
}
},
"pipelines": [
{
"name": "pipeline1",
"counter": 13,
"label": "13",
"natural_order": 13.0,
"can_run": true,
"preparing_to_schedule": false,
"comment": null,
"scheduled_date" : 1436519914578,
"build_cause": {
"trigger_message": "modified by user <user@users.noreply.github.com>",
"trigger_forced": false,
"approver": "",
"material_revisions": [
{
"changed": false,
"material": {
"name": "https://github.com/gocd/gocd",
"fingerprint": "de08b34d116a1cfc1fb988b6683bf21",
"type": "Git",
"description": "URL: https://github.com/gocd/gocd, Branch: master"
},
"modifications": [
{
"revision": "40f0a7ba43df37794cfc78b158483b",
"modified_time": 1436519914378,
"user_name": "user <user@users.noreply.github.com>",
"comment": "some commit message.",
"email_address": null
}
]
}
]
},
"stages": [
{
"result": "Failed",
"status" : "Failed",
"rerun_of_counter": null,
"name": "pipeline1_stage",
"counter": "1",
"scheduled": true,
"approval_type": "success",
"approved_by": "changes",
"operate_permission": true,
"can_run": true,
"jobs": [
{
"name": "pipeline1_job",
"scheduled_date": 1436582744378,
"state": "Completed",
"result": "Failed"
}
]
}
]
}
]
}
The pipeline history allows users to list pipeline instances. Supports cursor based pagination. The json output provides the next link which needs to be followed for the next set of records (if present). It also provides a previous which can be followed to get the previous page (if there is one).
The API supports the following query params:
| Param Name | Description |
|---|---|
page_size |
The number of records per page. Can be between 10 and 100. Defaults to 10 |
after |
The cursor value for fetching the next set of records |
before |
The cursor value for fetching the previous set of records |
Updated to version v1 since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/history
Returns
An array of pipeline instances.
Comment on pipeline instance
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/1/comment' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{"comment": "Failed bacause of flaky tests"}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Comment successfully updated."
}
The api allows users to comment on the pipeline instance. This can be used to share additional information like reason of failure or cancellation etc. The API requires user to have operate permissions on the pipeline.
Available since v19.12.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/:pipeline_counter/comment
Returns
A message confirming that the comment is updated on pipeline instance.
Pipelines
The pipelines API allows users to view pipeline information and operate on it.
Get pipeline status
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/status' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"paused": true,
"paused_cause": "Reason for pausing this pipeline",
"paused_by": "admin",
"locked": false,
"schedulable": false
}
The pipeline status allows users to check if the pipeline is paused, locked and schedulable.
Updated to version v1 since v20.1.0.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/status
Returns
JSON containing information about pipeline state.
Pause a pipeline
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/pause' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"pause_cause": "Investigating build failures"
}'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Pipeline 'pipeline1' paused successfully."
}
Pause the specified pipeline.
Available since v18.2.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/pause
The following properties may be specified.
| Attribute | Type | Description |
|---|---|---|
pause_cause |
String | Reason for pausing the pipeline. |
Returns
A message confirming that the pipeline was paused.
Unpause a pipeline
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/unpause' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'X-GoCD-Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Pipeline 'pipeline1' unpaused successfully."
}
Unpause the specified pipeline.
Available since v18.2.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/unpause
Returns
A message confirming that the pipeline was unpaused.
Releasing a pipeline lock
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/unlock' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'X-GoCD-Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Pipeline lock released for pipeline1."
}
Release a lock on a pipeline so that you can start up a new instance without having to wait for the earlier instance to finish.
Available since v18.2.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/unlock
Returns
A message confirming that the pipeline was unlocked.
Scheduling pipelines
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/schedule' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"environment_variables": [
{
"name": "USERNAME",
"secure": false,
"value": "bob"
},
{
"name": "SSH_PASSPHRASE",
"value": "some passphrase",
"secure": true,
},
{
"name": "PASSWORD",
"encrypted_value": "YEepp1G0C05SpP0fcp4Jh+kPmWwXH5Nq",
"secure": true,
}
],
"materials": [
{
"fingerprint": "b5bb9d8014a0f9b1d61e21e796d78dccdf1352f23cd32812f4850b878ae4944c",
"revision": "123"
},
{
"fingerprint": "7d865e959b2466918c9863afca942d0fb89d7c9ac0c99bafc3749504ded97730",
"revision": "1058e75b18e8a645dd71702851994a010789f450"
}
],
"update_materials_before_scheduling": true
}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"message" : "Request to schedule pipeline pipeline1 accepted"
}
Scheduling allows user to trigger a specific pipeline.
Available since v18.2.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/schedule
The following properties may be specified.
| Attribute | Type | Description |
|---|---|---|
environment_variables |
Array | A list of environment variables that can be overridden while scheduling the pipeline. |
materials |
Array | A list of materials that must be used to trigger a new instance of the pipeline. Defaults to triggering with the latest revision of all pipelines. |
update_materials_before_scheduling |
Boolean | Whether a material update should be updated before scheduling. See more information about this flag below. Defaults to true. |
Returns
A message indicating if the request was accepted.
The update_materials_before_scheduling flag
When the update_materials_before_scheduling flag is false, then GoCD does not run a material update before scheduling the pipeline.
When the update_materials_before_scheduling flag is true (as it is by default), then a material update is run before the pipeline is scheduled. This can cause new commits to be seen for the materials of the pipeline, causing GoCD to use those commits for scheduling the pipeline.
Scenario 1:
Given:
update_materials_before_scheduling:falsematerials: empty list
What happens:
- No material update happens.
- The latest known revisions of all the materials of the pipeline are used.
Scenario 2:
Given:
update_materials_before_scheduling:falsematerials: non-empty list
What happens:
- No material update happens.
- The specified revisions of the materials will be used.
- The latest known revisions of all other (unspecified) materials will be used.
- If any of the revisions cannot be found, the pipeline will fail to be triggered.
Scenario 3:
Given:
update_materials_before_scheduling:truematerials: empty list
What happens:
- Material update happens.
- The latest known revisions of all the materials of the pipeline are used. Any new revisions found during the material update will be used.
Scenario 4:
Given:
update_materials_before_scheduling:truematerials: non-empty list
What happens:
- Material update happens.
- The specified revisions of the materials will be used.
- The latest known revisions of all other (unspecified) materials will be used. These might be new revisions found during the material update.
- If any of the revisions cannot be found, the pipeline will fail to be triggered.
Please see GitHub issue #4319 for more information and details.
The scheduling material object
{
"materials": [
{
"fingerprint": "5ae0ad30a5daf288a5d5ad0779f5599e18628079db282b9979a5a1647e7d6064",
"revision": "123"
},
{
"fingerprint": "06cd91c5bae482aef5b26d48e22e6f2e2dd7c9e880e02d55ce16e5aafc3c0c4b",
"revision": "ccfbcd41f7d9dd2f10323d9a4f19c7f0aa5f6fe0"
},
{
"fingerprint": "bc3f161b22bef8b027446e0fb56a1c6dda5d02c14bbbe1415b428fcf949aaa09",
"revision": "upstream_foo/2/dist/1"
},
{
"fingerprint": "29f7131be1c8475331e17dbde34df03483d17c711ecbc36427ead6ec6408666f",
"revision": "gcc-4.4.7-3.el6.x86_64"
}
]
}
| Attribute | Type | Description |
|---|---|---|
fingerprint |
String | The fingerprint of the material object. |
revision |
String | The revision of the material that should be used to trigger the pipeline:
|
Compare pipeline instances
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/compare/1/3' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v2+json; charset=utf-8
{
"_links" : {
"self" : {
"href" : "http://ci.example.com/go/api/pipelines/:pipeline_name/compare/:from_counter/:to_counter"
},
"doc" : {
"href" : "https://api.gocd.org/current/#compare-pipeline-instances"
}
},
"pipeline_name" : "pipeline1",
"from_counter" : 1,
"to_counter" : 3,
"is_bisect" : false,
"changes" : [ {
"material" : {
"type" : "git",
"attributes" : {
"destination" : null,
"filter" : null,
"invert_filter" : false,
"name" : null,
"auto_update" : true,
"url" : "git@github.com:sample_repo/example.git",
"branch" : "master",
"submodule_folder" : null,
"shallow_clone" : false ,
"display_type": "Git",
"description": "URL: git@github.com:sample_repo/example.git, Branch: master"
}
},
"revision" : [ {
"revision_sha" : "some-random-sha",
"modified_by" : "username <username@github.com>",
"modified_at" : "2019-10-15T12:32:37Z",
"commit_message" : "some commit message"
} ]
}, {
"material" : {
"type" : "dependency",
"attributes" : {
"pipeline" : "upstream",
"stage" : "upstream_stage",
"name" : "upstream_material",
"auto_update" : true ,
"display_type": "Pipeline",
"description": "upstream [ upstream_stage ]"
}
},
"revision" : [ {
"revision" : "upstream/1/upstream_stage/1",
"pipeline_counter" : "1",
"completed_at" : "2019-10-17T06:55:07Z"
} ]
} ]
}
The compare pipeline API allows users to find the difference in the materials between the two instance.
Updated to version v2 since v20.2.0.
Available since v19.10.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/compare/:from_counter/:to_counter
Returns
The comparison result object
| Attribute | Type | Description |
|---|---|---|
pipeline_name |
String | The name of the pipeline. |
from_counter |
Integer | The instance count which is being compared. |
to_counter |
Integer | The instance count to which the above instance is compared. |
is_bisect |
Boolean | States whether or not either one of the instances is a bisection. If true, it means that the instances are not directly comparable, since at least one of them was manually triggered with older revisions of materials and the comparison might not make sense because of the chosen revisions. |
changes |
Array | The list of all the changes in terms of materials and upstream dependencies. |
The changes object
| Attribute | Type | Description |
|---|---|---|
material |
Object | The material config. |
revision |
Array | The list of all the material revisions or dependency revision which were used in the pipeline instance. |
The change material object
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a material. Can be one of git, svn, hg, p4, tfs, dependency, package, plugin. |
attributes |
Object | The attributes for each material type. |
The material revision object
| Attribute | Type | Description |
|---|---|---|
revision_sha |
String | The revision SHA. |
modified_by |
String | The username who added the revision. |
modified_at |
String | The time at which the revision was added. |
commit_message |
String | The revision message added. |
The dependency revision object
| Attribute | Type | Description |
|---|---|---|
revision |
String | The upstream pipeline label. |
pipeline_counter |
Integer | The upstream pipeline counter which was used as material in the instance. |
completed_at |
String | The time at which the upstream pipeline completed. |
The compare git material attributes
{
"type": "git",
"attributes": {
"url": "https://github.com/gocd/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "master",
"auto_update": true,
"display_type": "Git",
"description": "Git - URL: https://github.com/gocd/api.go.cd, Branch: master"
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the git repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
encrypted_password |
String | The encrypted password for the specified user. Since v19.4.0. |
branch |
String | The git branch to build. |
auto_update |
Boolean | Whether to poll for new changes or not. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare svn material attributes
{
"type": "svn",
"attributes": {
"url": "svn://svn.example.com/myProject/trunk",
"username": "admin",
"auto_update": true,
"encrypted_password": "aSdiFgRRZ6A=",
"check_externals": true,
"display_type": "Subversion",
"description": "URL: svn://svn.example.com/myProject/trunk, Username: admin, CheckExternals: true"
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the subversion repository. |
username |
String | The user account for the remote repository. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
auto_update |
Boolean | Whether to poll for new changes or not. |
check_externals |
Boolean | Whether the changes o the externals will trigger the pipeline automatically or not. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare mercurial material attributes
{
"type": "hg",
"attributes": {
"url": "http://hg.example.com/hg/api.go.cd",
"username": "bob",
"encrypted_password": "aSdiFgRRZ6A=",
"branch": "feature",
"auto_update": true,
"display_type": "Mercurial",
"description": "URL: http://hg.example.com/hg/api.go.cd"
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL of the mercurial repository. |
username |
String | The user account for the remote repository. Since v19.4.0. |
password |
String | The password for the specified user. Since v19.4.0. |
encrypted_password |
String | The encrypted password for the specified user. Since v19.4.0. |
branch |
String | The mercurial branch to build. Since v19.4.0. |
auto_update |
Boolean | Whether to poll for new changes or not. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare perforce material attributes
{
"type": "p4",
"attributes": {
"port": "p4.example.com:8080",
"use_tickets": true,
"view": "sample_view",
"auto_update": true,
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A=",
"display_type": "Perforce",
"description": "URL: p4.example.com:8080, View: sample_view, Username: admin"
}
}
| Attribute | Type | Description |
|---|---|---|
port |
String | Perforce server connection to use ([transport:]host:port). |
use_tickets |
Boolean | Whether to work with the Perforce tickets or not. |
view |
String | The Perforce view. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username to be used. |
password |
String | The password for the specified user. |
encrypted_password |
String | The encrypted password for the specified user. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare tfs material attributes
{
"type": "tfs",
"attributes": {
"url": "http://tfs.exampe.com:8000/tfs",
"project_path": "$/",
"domain": "corporate/domain",
"username": "admin",
"encrypted_password": "aSdiFgRRZ6A=",
"display_type": "Tfs",
"description": "URL: http://tfs.exampe.com:8000/tfs, Username: admin, Domain: corporate/domain, ProjectPath: $/"
}
}
| Attribute | Type | Description |
|---|---|---|
url |
String | The URL for the Collection on the TFS Server. |
project_path |
String | The project path within the TFS collection. |
domain |
String | The domain name for TFS authentication credentials. |
auto_update |
Boolean | Whether to poll for new changes or not. |
username |
String | The username of the account to access the TFS collection. |
password |
String | The password of the account to access the TFS collection. |
encrypted_password |
String | The encrypted password of the account to access the TFS collection. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare dependency material attributes
{
"type": "dependency",
"attributes": {
"name": "name",
"pipeline": "pipeline-name",
"stage": "stage-name",
"auto_update": true,
"display_type": "Pipeline",
"description": "pipeline-name [ stage-name ]"
}
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the dependency material. |
pipeline |
String | The name of the upstream pipeline. |
stage |
String | The name of the stage of the upstream pipeline. |
auto_update |
Boolean | Whether the material should be updated on a successful run (Always true). |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare package material attributes
{
"type": "package",
"attributes": {
"ref": "e289f497-057b-46bc-bb69-8043454f5c1b",
"display_type": "Package",
"description": "Repository: [] - Package: []"
}
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique package repository id. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
The compare plugin material attributes
{
"type": "plugin",
"attributes": {
"ref": "scm-id",
"filter": {
"ignore": [
"**/*.html",
"**/foobar/"
]
},
"destination": "des-folder",
"display_type": "SCM",
"description": "k1:v1"
}
}
| Attribute | Type | Description |
|---|---|---|
ref |
String | The unique id for the plugin material. |
filter |
Object | Contains the filter properties. E.g. files to ignore. |
destination |
String | The folder name to checkout to. |
display_type |
String | The display type for the given material. Since v20.2.0. |
description |
String | A brief description about the material. Since v20.2.0. |
Plugin Info
The plugin info API allows users with administrator role to fetch information about installed plugins.
The plugin info object
Available since v19.3.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | Plugin unique identifier. |
status |
Object | The status of the plugin. |
plugin_file_location |
String | The location where the plugin is installed. |
bundled_plugin |
Boolean | Indicates whether the plugin is bundled with GoCD. |
about |
Object | Additional details about the plugin. |
extensions |
Array | A list of extension information pertaining to the list of extensions the plugin implements. |
The plugin status object
{
"state": "invalid",
"messages": [
"Plugin not supported"
]
}
| Attribute | Type | Description |
|---|---|---|
state |
String | Status of the plugin. Can be one of active, invalid. |
messages |
Array | Array of messages stating the reason why the plugin isn’t loaded. The messages are shown only if the status is invalid. |
The plugin vendor object
{
"name": "GoCD contributors",
"url": "http://thoughtworks.com"
}
| Attribute | Type | Description |
|---|---|---|
name |
String | Name of the plugin author. |
url |
String | Link to know more details about the plugin author. |
The plugin about object
{
"name": "GitHub Pull Requests Builder",
"version": "1.3.3",
"target_go_version": "15.1.0",
"description": "Plugin that polls a GitHub repository for pull requests and triggers a build for each of them",
"target_operating_systems": [
],
"vendor": {
"name": "GoCD contributors",
"url": "http://thoughtworks.com"
}
}
| Attribute | Type | Description |
|---|---|---|
name |
String | Name of the plugin. |
version |
String | Version of the plugin that’s installed. |
target_go_version |
String | Minimal version of GoCD required for the plugin to work. |
description |
String | Short description about what the plugin does. |
target_operating_systems |
Array | List of operating systems on which the plugin is expected to work. |
vendor |
Object | Details about the plugin author. |
Extension information object: Config repo
{
"extensions": [
{
"type": "configrepo",
"plugin_settings": {
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
},
"capabilities": {
"supports_pipeline_export": true,
"supports_parse_content": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is configrepo. |
plugin_settings |
Object | The html view for the plugin and the list of properties required to be configured. |
capabilities |
Object | The capabilities object indicates the enhancements that a plugin provides. |
Extension information object: Elastic agent
{
"extensions": [
{
"type": "elastic",
"elastic_agent_profile_settings": {
"configurations": [
{
"key": "Image",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Elastic agent profile template</div>"
}
},
"supports_cluster_profiles": true,
"cluster_profile_settings": {
"configurations": [
{
"key": "EfsDnsOrIP",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Cluster Profile view template</div>"
}
},
"capabilities": {
"supports_plugin_status_report": true,
"supports_agent_status_report": true,
"supports_cluster_status_report": true
}
},
{
"type": "elastic",
"elastic_agent_profile_settings": {
"configurations": [
{
"key": "Image",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Elastic agent profile template</div>"
}
},
"supports_cluster_profiles": false,
"plugin_settings": {
"configurations": [
{
"key": "EfsDnsOrIP",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
},
"capabilities": {
"supports_plugin_status_report": true,
"supports_agent_status_report": true,
"supports_cluster_status_report": false
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is elastic. |
plugin_settings |
Object | The html view for the plugin and the list of properties required to be configured. Present in case of plugin supports plugin settings. . |
supports_cluster_profiles |
Boolean | Boolean indicating whether plugin supports defining cluster profiles. |
elastic_agent_profile_settings |
Object | The html view for the elastic agent profile and the list of properties required to be configured. |
cluster_profile_settings |
Object | The html view for the cluster profile and the list of properties required to be configured. Present in case of plugin supports defining cluster profiles. |
capabilities |
Object | The capabilities object indicates the enhancements that a plugin provides. |
Extension information object: Authorization
{
"extensions": [
{
"type": "authorization",
"auth_config_settings": {
"configurations": [
{
"key": "Id",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Auth view template</div>"
}
},
"role_settings": {
"configurations": [
{
"key": "Name",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Role view template</div>"
}
},
"capabilities": {
"can_search": true,
"supported_auth_type": "password",
"can_authorize": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is authorization. |
auth_config_settings |
Object | The html view for auth config and the list of properties that can be used to configure auth configs. |
role_settings |
Object | The html view for role config and the list of properties that can be used to configure role configs. |
capabilities |
Object | The capabilities object indicates the enhancements that a plugin provides. |
Extension information object: SCM
{
"extensions": [
{
"type": "scm",
"display_name": "Github",
"scm_settings": {
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true,
"part_of_identity": true
}
}
],
"view": {
"template": "<div>Scm view template</div>"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is scm. |
display_name |
String | The descriptive name of the plugin. |
scm_settings |
Object | The html view for pluggable scm and the list of properties that can be used to configure the pluggable scm material. |
Extension information object: Task
{
"extensions": [
{
"type": "task",
"display_name": "Task",
"task_settings": {
"configurations": [
{
"key": "script",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>task view template</div>"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is task. |
display_name |
String | The descriptive name of the plugin. |
task_settings |
Object | The html view for pluggable task and the list of properties that can be used to configure the pluggable task. |
Extension information object: Package repo
{
"extensions": [
{
"type": "package-repository",
"package_settings": {
"configurations": [
{
"key": "PACKAGE_SPEC",
"metadata": {
"secure": false,
"display_order": 0,
"required": true,
"part_of_identity": false,
"display_name": "Package Spec"
}
}
]
},
"repository_settings": {
"configurations": [
{
"key": "REPO_URL",
"metadata": {
"secure": false,
"display_order": 0,
"required": true,
"part_of_identity": false,
"display_name": "Repository URL"
}
}
]
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is package-repository. |
package_settings |
Object | The list of properties that can be used to configure a package material. A form is created for the user based on these properties. No request is currently made to fetch the view for package settings. |
repository_settings |
Object | The list of properties that can be used to configure package repositories. A form is created for the user based on these properties. No request is currently made to fetch the view for repository settings. |
Extension information object: Notification
{
"extensions": [
{
"type": "notification",
"plugin_settings": {
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is notification. |
plugin_settings |
Object | The html view for the plugin and the list of properties required to be configured. |
Extension information object: Analytics
{
"extensions": [
{
"type": "analytics",
"plugin_settings": {
"configurations": [
{
"key": "analytics_source_url",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
},
"capabilities": {
"supported_analytics": [
{
"type": "pipeline",
"id": "pipeline_duration",
"title": "Pipeline Duration"
}
]
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is analytics. |
plugin_settings |
Object | The html view for the plugin and the list of properties required to be configured. |
capabilities |
Object | The capabilities object indicates the enhancements that a plugin provides. |
Extension information object: Artifact
{
"extensions": [
{
"type": "artifact",
"store_config_settings": {
"configurations": [
{
"key": "RegistryURL",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
},
"artifact_config_settings": {
"configurations": [
{
"key": "BuildFile",
"metadata": {
"secure": false,
"required": false
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
},
"fetch_artifact_settings": {
"configurations": [
{
"key": "EnvironmentVariablePrefix",
"metadata": {
"secure": false,
"required": false
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is artifact. |
store_config_settings |
Object | The html view to configure the artifact store and the list of properties that can be used to configure the artifact store. |
artifact_config_settings |
Object | The html view to configure the publish artifact configs and the list of properties that can be used to configure publish artifact config. |
fetch_artifact_settings |
Object | The html view to configure the fetch artifact config and the list of properties that can be used to configure fetch artifact config. |
Extension information object: Secrets
{
"extensions": [
{
"type": "secrets",
"secret_config_settings": {
"configurations": [
{
"key": "FilePath",
"metadata": {
"secure": false,
"required": true
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the extension, which is secrets. |
secret_config_settings |
Object | The html view to configure the secret configs and the list of properties that can be used to configure the secret configs. |
The plugin info configurations object
{
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | Describes the configuration key. |
metadata |
Object | Metadata for the configuration property. The metadata consists of attributes secure, required. The attributes for package-repository and scm plugins are given below. |
The package repository configurations object
{
"configurations": [
{
"key": "REPO_URL",
"metadata": {
"secure": false,
"display_order": 0,
"required": true,
"part_of_identity": false,
"display_name": "Repository URL"
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | Describes the configuration key for a repository configuration property. |
metadata |
Object | Metadata for the configuration property. |
The scm configurations object
{
"configurations": [
{
"key": "REPO_URL",
"metadata": {
"secure": false,
"required": true,
"part_of_identity": false
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | Describes the configuration key for a repository configuration property. |
metadata |
Object | Metadata for the configuration property. |
The plugin info view object
{
"view": {
"template": "<div>Plugin view template</div>"
}
}
| Attribute | Type | Description |
|---|---|---|
template |
String | The plugin Angular.js view template. |
The Config Repo Capabilities object
{
"capabilities": {
"supports_pipeline_export": true,
"supports_parse_content": true,
"supports_list_config_files": false,
"supports_user_defined_properties": true
}
}
| Attribute | Type | Description |
|---|---|---|
supports_pipeline_export |
Boolean | Indicates if plugin supports pipeline configuration export. |
supports_parse_content |
Boolean | Indicates if plugin supports parse content. |
supports_list_config_files |
Boolean | Indicates if plugin supports listing of config files in the given repo. |
supports_user_defined_properties |
Boolean | Indicates if plugin supports user defined configurations. |
The Elastic Agents Capabilities object
{
"capabilities": {
"supports_plugin_status_report": true,
"supports_agent_status_report": true,
"supports_cluster_status_report": true
}
}
| Attribute | Type | Description |
|---|---|---|
supports_plugin_status_report |
Boolean | Indicates if plugin supports plugin level status report. |
supports_agent_status_report |
Boolean | Indicates if plugin supports elastic agent status report for a specific agent. |
supports_cluster_status_report |
Boolean | Indicates if plugin supports cluster profile status report for a specific agent. |
The Authorization Capabilities object
{
"capabilities": {
"can_search": true,
"supported_auth_type": "password",
"can_authorize": true
}
}
| Attribute | Type | Description |
|---|---|---|
can_search |
Boolean | Indicates if plugin supports user search. |
supported_auth_type |
String | Specifies the type of authentication supported, can be one of password or web. |
can_authorize |
Boolean | Indicates if plugin supports authorization. |
The Analytics Capabilities object
The analytics capablities contains a list of supported_analytics, with the following attributes.
{
"capabilities": {
"supported_analytics": [
{
"type": "pipeline",
"id": "pipeline_duration",
"title": "Pipeline Duration"
}
]
}
}
| Attribute | Type | Description |
|---|---|---|
id |
String | Unique identifier for an analytics. |
title |
String | Title for the analytics. |
type |
String | The type of the analytics. |
Get all plugin info
$ curl 'https://ci.example.com/go/api/admin/plugin_info' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
"_links": {
"self": {
"href": "http://localhost:8153/go/api/admin/plugin_info"
},
"find": {
"href": "http://localhost:8153/go/api/admin/plugin_info/:plugin_id"
},
"doc": {
"href": "https://api.gocd.org/#plugin-info"
}
},
"_embedded": {
"plugin_info": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_info/json.config.plugin"
},
"doc": {
"href": "https://api.gocd.org/#plugin-info"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_info/:id"
}
},
"id": "json.config.plugin",
"status": {
"state": "active"
},
"plugin_file_location": "/Users/varshavs/gocd/server/plugins/bundled/gocd-json-config-plugin.jar",
"bundled_plugin": true,
"about": {
"name": "JSON Configuration Plugin",
"version": "0.2",
"target_go_version": "16.1.0",
"description": "Configuration plugin that supports GoCD configuration in JSON",
"target_operating_systems": [
],
"vendor": {
"name": "Tomasz Setkowski",
"url": "https://github.com/tomzo/gocd-json-config-plugin"
}
},
"extensions": [
{
"type": "configrepo",
"plugin_settings": {
"configurations": [
{
"key": "pipeline_pattern",
"metadata": {
"secure": false,
"required": false
}
},
{
"key": "environment_pattern",
"metadata": {
"secure": false,
"required": false
}
}
],
"view": {
"template": "Some view"
}
}
}
]
}
]
}
}
Lists all available plugin info.
Updated to version v7 since v20.8.0.
Available since v19.3.0.
HTTP Request
GET /go/api/admin/plugin_info
Returns
An array of plugin info objects.
Get plugin info
$ curl 'https://ci.example.com/go/api/admin/plugin_info/my_plugin' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v7+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v7+json; charset=utf-8
ETag: "4167e3ec81fdac0fb29d854b36ceb981"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_info/my_plugin"
},
"doc": {
"href": "https://api.gocd.org/#plugin-info"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_info/:id"
}
},
"id": "my_plugin",
"status": {
"state": "active"
},
"plugin_file_location": "/path/to/server/plugins/external/my_plugin.jar",
"bundled_plugin": false,
"about": {
"name": "My Plugin",
"version": "0.2",
"target_go_version": "16.1.0",
"description": "Short desc",
"target_operating_systems": [
],
"vendor": {
"name": "GoCD contributors",
"url": "https://github.com/tomzo/gocd-json-config-plugin"
}
},
"extensions": [
{
"type": "configrepo",
"plugin_settings": {
"configurations": [
{
"key": "pipeline_pattern",
"metadata": {
"secure": false,
"required": false
}
},
{
"key": "environment_pattern",
"metadata": {
"secure": false,
"required": false
}
}
],
"view": {
"template": "Some view"
}
}
}
]
}
Gets plugin info for a specified plugin id.
Updated to version v7 since v20.8.0.
Available since v19.3.0.
HTTP Request
GET /go/api/admin/plugin_info/:id
Returns
The plugin info object.
Server Health
The server health API allows users to monitor if the GoCD server is up and running. Usually used for health checks in Docker and Kubernetes.
Check Server Health
$ curl 'https://ci.example.com/go/api/v1/health'
The above command returns a json response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"health": "OK"
}
This API will indicate if the server is up.
Available since v17.11.0.
HTTP Request
GET /go/api/v1/health
Server Health Messages
The server health messages API allows users to see any errors and warnings generated by the GoCD server as part of its normal routine. These messages are also visible in on the “errors and warnings” modal box on all pages of the GoCD server.
The server health message object
Available since v18.2.0.
| Attribute | Type | Description |
|---|---|---|
message |
String | A short summary of the error or warning. |
detail |
String | A longer message with more details about the error. |
level |
String | The intensity of the message. Can be one of WARNING, ERROR. |
time |
String | The UTC time when the message was gnerated. |
Get server health messages
$ curl 'https://ci.example.com/go/api/server_health_messages' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
[{
"message" : "Job 'Security-Checks/test/dependency-check' is not responding",
"detail" : "Job <a href='/go/tab/build/detail/Security-Checks/847/test/1/dependency-check'>Security-Checks/test/dependency-check</a> is currently running but has not shown any console activity in the last 26 minute(s). This job may be hung.",
"level" : "WARNING",
"time" : "2018-02-27T07:36:30Z"
}]
Gets the current server health messages
Available since v18.2.0.
HTTP Request
GET /go/api/server_health_messages
Returns
An array of server health message objects.
Stage Instances
The Stage Instances API allows users to view and operate on an instance of a stage.
Cancel stage
$ curl 'https://ci.example.com/go/api/stages/myPipeline/42/myStages/13/cancel' \
-u 'username:password' \
-H 'X-GoCD-Confirm: true' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json;charset=utf-8
{
"message" : "Stage cancelled successfully."
}
Cancel an active stage of a specified stage.
Updated to version v3 since v20.9.0.
Available since v14.3.0.
HTTP Request
POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/cancel
Returns
A message confirmation if the stage was cancelled.
Get stage instance
$ curl 'https://ci.example.com/go/api/stages/myPipeline/1/myStages/1' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json;charset=utf-8
{
"name": "default_stage",
"counter": 1,
"approval_type": "success",
"approved_by": "changes",
"scheduled_at": 1578891141997,
"last_transitioned_time": 1436509642631,
"result": "Unknown",
"rerun_of_counter": null,
"fetch_materials": true,
"clean_working_directory": false,
"artifacts_deleted": false,
"pipeline_name": "default",
"pipeline_counter": 1,
"jobs": [
{
"name": "default_job",
"state": "Scheduled",
"result": "Unknown",
"scheduled_date": 1578891141997,
"rerun": false,
"original_job_id": null,
"agent_uuid": null,
"pipeline_name": null,
"pipeline_counter": null,
"stage_name": null,
"stage_counter": null,
"job_state_transitions": [
{
"state": "Scheduled",
"state_change_time": 1578891141997
},
{
"state": "Assigned",
"state_change_time": 1436509524491
},
{
"state": "Preparing",
"state_change_time": 1436509534639
},
{
"state": "Building",
"state_change_time": 1436509542522
},
{
"state": "Completing",
"state_change_time": 1436509642582
},
{
"state": "Completed",
"state_change_time": 1436509642631
}
]
}
]
}
Gets stage instance object.
Updated to version v3 since v20.9.0.
Available since v19.1.0.
HTTP Request
GET /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter
Returns
A stage instance object.
Get stage history
$ curl 'https://ci.example.com/go/api/stages/mypipeline/defaultStage/history' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"next": {
"href": "http://ci.example.com/go/api/stages/mypipeline/defaultStage/history?after=38"
},
"previous": {
"href": "http://ci.example.com/go/api/stages/mypipeline/defaultStage/history?before=4"
}
},
"stages": [
{
"name": "defaultStage",
"approved_by": "admin",
"cancelled_by": "GoCD",
"jobs": [
{
"name": "defaultJob",
"result": "Cancelled",
"state": "Completed",
"scheduled_date": 1436509881002
}
],
"pipeline_counter": 3,
"pipeline_name": "mypipeline",
"result": "Cancelled",
"approval_type": "success",
"counter": "1",
"rerun_of_counter": null
},
{
"name": "defaultStage",
"approved_by": "admin",
"cancelled_by": "admin",
"jobs": [
{
"name": "defaultJob",
"result": "Cancelled",
"state": "Completed",
"scheduled_date": 1436509783931
}
],
"pipeline_counter": 2,
"pipeline_name": "mypipeline",
"result": "Cancelled",
"approval_type": "success",
"counter": "1",
"rerun_of_counter": null
},
{
"name": "defaultStage",
"approved_by": "changes",
"jobs": [
{
"name": "defaultJob",
"result": "Passed",
"state": "Completed",
"scheduled_date": 1436509518752
}
],
"pipeline_counter": 1,
"pipeline_name": "mypipeline",
"result": "Passed",
"approval_type": "success",
"counter": "1",
"rerun_of_counter": null
}
]
}
The stage history allows users to list stage instances of specified stage. Supports cursor based pagination. The json output provides the next link which needs to be followed for the next set of records (if present). It also provides a previous which can be followed to get the previous page (if there is one).
The API supports the following query params:
| Param Name | Description |
|---|---|
page_size |
The number of records per page. Can be between 10 and 100. Defaults to 10 |
after |
The cursor value for fetching the next set of records |
before |
The cursor value for fetching the previous set of records |
Updated to version v3 since v20.9.0.
Available since v14.3.0.
HTTP Request
GET /go/api/stages/:pipeline_name/:stage_name/history
Returns
An array of stage instances.
Run failed jobs
$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStage/myStageCounter/run-failed-jobs' \
-u 'username:password' \
-H 'X-GoCD-Confirm: true' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X POST
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v3+json;charset=utf-8
{
"message" : "Request to rerun jobs accepted"
}
Runs failed jobs in a completed stage.
Updated to version v3 since v20.9.0.
Available since v18.11.0.
HTTP Request
POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/run-failed-jobs
Returns
A message confirmation if the request to rerun failed jobs was accepted.
Run selected jobs
$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStage/myStageCounter/run-selected-jobs' \
-u 'username:password' \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.go.cd.v3+json'
-X POST \
-d '{
jobs: ["job1", "job2"]
}'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v3+json;charset=utf-8
{
"message" : "Request to rerun jobs accepted"
}
Runs specified jobs in a completed stage.
Updated to version v3 since v20.9.0.
Available since v18.11.0.
HTTP Request
POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/run-selected-jobs
Following property must be specified:
| Attribute | Type | Description |
|---|---|---|
jobs |
Array | A list job names that needs to be triggered again. This attribute MUST be specified. |
Returns
A message confirmation if the request to rerun selected jobs was accepted.
Stages
The stages API allows users to operate on a stage.
Run stage
$ curl 'https://ci.example.com/go/api/stages/myPipeline/myPipelineRunCounter/myStages/run' \
-u 'username:password' \
-H 'X-GoCD-Confirm: true' \
-H 'Accept: application/vnd.go.cd.v2+json' \
-X POST
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: application/vnd.go.cd.v2+json;charset=utf-8
{
"message" : "Request to schedule stage testAPI/1/defaultStage accepted"
}
Runs a specified stage.
Updated to version v2 since v20.1.0.
Available since v18.11.0.
HTTP Request
POST /go/api/stages/:pipeline_name/:pipeline_counter/:stage_name/run
Returns
A message confirmation if the request to schedule stage was accepted.
Users
The users API allows users with administrator role to manage users.
The user object
Available since v15.2.0.
| Attribute | Type | Description |
|---|---|---|
login_name |
String | The user’s login name. |
display_name |
String | The user’s display name. |
enabled |
Boolean | Boolean indicating if the user is enabled (can login in). |
email |
String | The user’s email address. |
email_me |
Boolean | Boolean indicating if the user has signed up for email notifications. |
checkin_aliases |
Array | A list of SCM checkin aliases to map users to SCM commits. |
admin |
Boolean | Boolean indicating if the user is an admin. Since v19.1.0. |
roles |
Array | List of user roles that the user has been assigned. Since v19.1.0. |
Get all users
$ curl 'https://ci.example.com/go/api/users' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/users"
},
"doc": {
"href": "https://api.gocd.org/#users"
}
},
"_embedded": {
"users": [
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/admin"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "John Doe",
"enabled": true,
"email": null,
"email_me": false,
"admin": false,
"roles": [{
"name": "role name",
"type": "gocd"
}],
"checkin_aliases": [
"jdoe",
"johndoe"
]
}
]
}
}
Lists all available users.
Available since v15.2.0.
HTTP Request
GET /go/api/users
Returns
An array of user objects.
Get one user
$ curl 'https://ci.example.com/go/api/users/jdoe' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/jdoe"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "jdoe",
"enabled": true,
"email": null,
"email_me": false,
"admin": true,
"roles": [{
"name": "role name",
"type": "gocd"
}],
"checkin_aliases": [
]
}
Gets a user by its login name
Available since v15.2.0.
HTTP Request
GET /go/api/users/:login_name
Returns
A user object.
Create a user
$ curl 'https://ci.example.com/go/api/users' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X POST \
-d '{
"email": "jdoe@example.com",
"login_name": "jdoe"
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/jdoe"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "jdoe",
"enabled": true,
"email": null,
"email_me": false,
"admin": false,
"roles": [{
"name": "role name",
"type": "gocd"
}],
"checkin_aliases": [
]
}
Creates a user
Available since v15.3.0.
HTTP Request
POST /go/api/users
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
login_name |
String | The user’s login name. This attribute MUST be specified. |
enabled |
Boolean | Boolean indicating if the user is enabled (can login in). |
email |
String | The user’s email address. |
email_me |
Boolean | Boolean indicating if the user should be signed up for email notifications. |
checkin_aliases |
Array | A list of SCM checkin aliases to map users to SCM commits. |
Returns
A user object.
Update a user
$ curl 'https://ci.example.com/go/api/users/jdoe' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"email": "jdoe@example.com",
"email_me": true,
"checkin_aliases": ["jdoe", "johndoe"]
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"_links": {
"doc": {
"href": "https://api.gocd.org/#users"
},
"self": {
"href": "https://ci.example.com/go/api/users/jdoe"
},
"find": {
"href": "https://ci.example.com/go/api/users/:login_name"
}
},
"login_name": "jdoe",
"display_name": "jdoe",
"enabled": false,
"email": "jdoe@example.com",
"email_me": true,
"admin": false,
"roles": [{
"name": "role name",
"type": "gocd"
}],
"checkin_aliases": [
"jdoe",
"johndoe"
]
}
Update some attributes of a user.
Available since v15.2.0.
HTTP Request
PATCH /go/api/users/:login_name
Atleast one of the following properties must be specified, not specifying the property will leave it unchanged.
| Attribute | Type | Description |
|---|---|---|
enabled |
Boolean | Boolean indicating if the user is enabled (can log in). |
email |
String | The user’s email address. |
email_me |
Boolean | Boolean indicating if the user should be signed up for email notifications. |
checkin_aliases |
Array | A list of SCM checkin aliases to map users to SCM commits. |
Returns
The updated user object.
Delete a user
$ curl 'https://ci.example.com/go/api/users/jdoe' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-X DELETE
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "User 'jdoe' was deleted successfully."
}
Deletes a user.
Available since v15.2.0.
HTTP Request
DELETE /go/api/users/:login_name
Returns
A message confirmation if the user was deleted.
Bulk Delete Users
$ curl 'https://ci.example.com/go/api/users' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X DELETE \
-d '{"users": ["jez", "tez"]}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "Users '[\"jez\", \"tez\"]' were deleted successfully."
}
Deletes multiple users.
Available since v17.11.0.
HTTP Request
DELETE /go/api/users
Returns
A message confirming if the users were deleted.
Bulk Enable/Disable Users
$ curl 'https://ci.example.com/go/api/admin/operations/state' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v3+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"users": ["jez", "tez"],
"operations": {
"enable": true
}
}'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v3+json; charset=utf-8
{
"message": "Users '[\"jez\", \"tez\"]' were enabled successfully."
}
Enables/Disables multiple users.
Available since v19.1.0.
HTTP Request
PATCH /go/api/users/operations/state
Returns
A message confirming if the users were enabled/disabled.
The user role object
Available since v19.1.0.
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of role (plugin | gocd). |
Name |
String | Name of the role. |
Version
The Version API allows users to get the GoCD server version details.
The version object
Available since v16.6.0.
| Attribute | Type | Description |
|---|---|---|
version |
String | The GoCD server version. |
build_number |
Integer | The GoCD server build number. |
git_sha |
String | The git SHA from which this server version was built. |
full_version |
String | The GoCD server full version. |
commit_url |
String | TThe GitHub url to the git_sha. |
Get version
$ curl 'https://ci.example.com/go/api/version' \
-H 'Accept: application/vnd.go.cd.v1+json'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
{
"_links": {
"self": {
"href": "https://build.go.cd/go/api/version"
},
"doc": {
"href": "https://api.gocd.org/#version"
}
},
"version": "16.6.0",
"build_number": "3348",
"git_sha": "a7a5717cbd60c30006314fb8dd529796c93adaf0",
"full_version": "16.6.0 (3348-a7a5717cbd60c30006314fb8dd529796c93adaf0)",
"commit_url": "https://github.com/gocd/gocd/commits/a7a5717cbd60c30006314fb8dd529796c93adaf0"
}
Gets the current GoCD server details
Available since v16.6.0.
HTTP Request
GET /go/api/version
Returns
The version object.
section_marker_placeholder:Other
Errors
GoCD uses the following HTTP status codes to indicate errors.
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – The request could not be understood. The client SHOULD NOT repeat the request without modifications. |
| 401 | Unauthorized – Your username or password is incorrect or you are not authorized to perform this action. |
| 403 | Forbidden – The resource requested is hidden for administrators only. |
| 404 | Not Found – The specified resource could not be found. |
| 405 | Method Not Allowed – You tried to access a resource with an invalid method. |
| 406 | Not Acceptable – You requested a format that isn’t json. |
| 409 | Conflict – The request could not be completed due to a conflict with the current state of the resource. |
| 410 | Gone – The resource requested has been removed from our servers. |
| 412 | Precondition Failed – The request could not be completed because the state of the resource is not the latest while being updated. |
| 422 | Unprocessible Entity – The server understood the request, but the request is semantically erroneous. |
| 500 | Internal Server Error – We had a problem with our server. Try again later. |
| 501 | Not implemented – The server does not support the functionality required to fulfill the request. |
| 503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |
API Changelog
The changelog is maintained starting from version 19.2.0 of GoCD. For changes from previous versions, see the release notes at https://gocd.org/releases.
Changes in 24.4.0
Added
- No additions in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 24.3.0
Added
- No additions in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 24.2.0
Added
- No additions in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 24.1.0
Added
- No additions in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 23.5.0
Added
- No additions in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 23.4.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 23.3.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 23.2.0
Added
- No addition in this release
Removed
- The Backups API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Dashboard API version 3 has been removed. Version 4 of the API is available, and users are encouraged to use it.
Deprecations
- No deprecations in this release
Changes in 23.1.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
Notifications of these deprecations were missed in earlier releases when new versions were introduced, however due to their limited use, stability over several years and minor changes from the deprecated versions, are planned for removal on an accelerated schedule.
- The Backups API version 1 has been deprecated in GoCD release v19.3.0. This version will be removed in GoCD release v23.2.0. Version 2 of the API is available, and users are encouraged to use it.
- The Dashboard API version 3 has been deprecated in GoCD release v19.10.0. This version will be removed in GoCD release v23.2.0. Version 4 of the API is available, and users are encouraged to use it.
Changes in 22.3.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 22.2.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 22.1.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 21.4.0
Added
- No addition in this release
Removed
- The Stage Instances API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
Deprecations
- No deprecations in this release
Changes in 21.3.0
Added
- No addition in this release
Removed
- No removals in this release
Deprecations
- No deprecations in this release
Changes in 21.2.0
Added
- No addition in this release
Removed
- The Pluggable SCM API version 3 has been removed. Version 4 of the API is available, and users are encouraged to use it.
- The Secret Config API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
Deprecations
- No deprecations in this release
Changes in 21.1.0
Added
- No addition in this release
Removed
- The Pipeline Config API version 10 has been removed. Version 11 of the API is available, and users are encouraged to use it.
- The Secret Config API version 1 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 6 has been removed. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 3 has been removed. Version 4 of the API is available, and users are encouraged to use it.
Deprecations
- The Pluggable SCM API version 3 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.2.0. Version 4 of the API is available, and users are encouraged to use it.
- The Secret Config API version 2 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.2.0. Version 3 of the API is available, and users are encouraged to use it.
Changes in 20.10.0
Added
- No changes
Removed
- No changes
Deprecations
- The Pipeline Config API version 10 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 11 of the API is available, and users are encouraged to use it.
- The Secret Config API version 1 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 2 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 6 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 3 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 4 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 3 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.1.0. Version 4 of the API is available, and users are encouraged to use it.
- The Secret Config API version 2 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.1.0. Version 3 of the API is available, and users are encouraged to use it.
Changes in 20.9.0
Updated
- Updated Webhook APIs to add support for pluggable SCMs
Added
- Introduced version 4 of the Pluggable SCM API.
- This version adds readonly property
origin. The value of origin will specify whether the SCM is present in a config-repo or is defined in GoCD. - The update/delete calls will now return
422in case the SCM is defined in a config repo.
- This version adds readonly property
- Introduced version 3 of the Secret Config API.
- This version adds support for
cluster_profileas entity type for rules.
- This version adds support for
- Stages endpoints have been regrouped and split between Stages and Stage Instances. Also, introduced version 3 of the Stage Instances API.
- Version 3 of the Stage Instances API updates the Get Stage Instance API to return additional attributes
scheduled_atandlast_transitioned_time.
- Version 3 of the Stage Instances API updates the Get Stage Instance API to return additional attributes
Removed
- The Scheduled Jobs API has been removed. The Feeds API for Scheduled Jobs is available as a replacement.
Deprecations
- The Pipeline Config API version 10 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 11 of the API is available, and users are encouraged to use it.
- The Secret Config API version 1 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 2 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 6 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 3 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 4 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 3 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.1.0. Version 4 of the API is available, and users are encouraged to use it.
- The Secret Config API version 2 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.1.0. Version 3 of the API is available, and users are encouraged to use it.
- The Stage Instances API version 2 has been deprecated in GoCD release v20.9.0. This version will be removed in GoCD release v21.1.0. Version 3 of the API is available, and users are encouraged to use it.
Changes in 20.8.0
Added
- Introduced version 11 of the Pipeline Config API.
- This version adds support for
invert_filterfor Plugin Materials to enableAllowList.
- This version adds support for
- Introduced version 2 of the Secret Config API.
- This version adds support for
package_repositoryandpluggable_scmas entity type for rules.
- This version adds support for
- Introduced version 7 of the Plugin Info API.
- This version returns the updated capabilities for Config Repo plugins.
- Introduced version 4 of the Config Repo API.
- Config Repo plugins now allows user defined configurations. This version introduces
is_secureproperty for user defined configurations.
- Config Repo plugins now allows user defined configurations. This version introduces
Removed
- The Agents API version 6 has been removed. Version 7 of the API is available, and users are encouraged to use it.
Deprecations
- The Scheduled Jobs API has beeen deprecated in GoCD release 20.6.0. This API will be removed in GoCD release v20.9.0. As a replacement, a new Feeds API for Scheduled Jobs is introduced.
- The Pipeline Config API version 10 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 11 of the API is available, and users are encouraged to use it.
- The Secret Config API version 1 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 2 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 6 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 3 has been deprecated in GoCD release v20.8.0. This version will be removed in GoCD release v20.11.0. Version 4 of the API is available, and users are encouraged to use it.
Changes in 20.7.0
Added
- No changes
Removed
- No changes
Deprecations
- The Agents API version 6 has been deprecated in GoCD release v20.5.0. This version will be removed in GoCD release v20.8.0. Version 7 of the API is available, and users are encouraged to use it.
- The Scheduled Jobs API has beeen deprecated in GoCD release 20.6.0. This API will be removed in GoCD release v20.9.0. As a replacement, a new Feeds API for Scheduled Jobs is introduced.
Changes in 20.6.0
Added
Introduced feeds API for Scheduled Jobs.
Removed
- The Data Sharing Settings API version 1 has been removed.
- The Pluggable SCM API version 1 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Packages API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Materials API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
Deprecations
- The Agents API version 6 has been deprecated in GoCD release v20.5.0. This version will be removed in GoCD release v20.8.0. Version 7 of the API is available, and users are encouraged to use it.
- The Scheduled Jobs API has beeen deprecated in GoCD release 20.6.0. This API will be removed in GoCD release v20.9.0. As a replacement, a new Feeds API for Scheduled Jobs is introduced.
Changes in 20.5.0
Added
- Introduced version 7 of the Agents API.
- A new endpoint
Kill running tasksAPI was added in this version. - The GET
AgentsAPI and GET ‘All Agents’ API has been enhanced to return theagent_versionandagent_bootstrapper_version. - All other Agents API were just bumped up (version increased to 7) with no change to payload and response.
- A new endpoint
Removed
- The Pipeline Comparison API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Config Repo API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Template Config API version 6 has been removed. Version 7 of the API is available, and users are encouraged to use it.
Deprecations
- The Pluggable SCM API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 2 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Packages API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 2 of the API is available, and users are encouraged to use it.
- The Agents API version 6 has been deprecated in GoCD release v20.5.0. This version will be removed in GoCD release v20.8.0. Version 7 of the API is available, and users are encouraged to use it.
Changes in 20.4.0
Added
-
Removed
- The unversioned Job History API has been removed. Version 1 of the API is available, and users are encouraged to use it.
- The Stage API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Status API has been removed. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Instance API has been removed. Version 1 of the API is available, and users are encouraged to use it.
- The Notification Filter API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The older Feeds API in rails has been removed, and is replaced by the re-written new Feeds API Feeds without any changes to the contract.
Deprecations
- The Pluggable SCM API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 2 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Packages API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 2 of the API is available, and users are encouraged to use it.
- The Template Config API version 6 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 2 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 3 of the API is available, and users are encouraged to use it.
- The Pipeline Comparison API version 1 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 2 of the API is available, and users are encouraged to use it.
Changes in 20.3.0
Added
- Introduced version 2 of the Packages API.
- The
UsagesAPI was added in this version. - All other Package API were just bumped up (version increased to 2) with no change to payload and response.
- The
- Introduced version 3 of the SCM API.
- The
UsagesAPI was added in this version. - All other Pluggable SCM APIs were just bumped up (version increased to 3) with no change to payload and response.
- The
Removed
- The unversioned Agent Job History API has been removed. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Group Config Listing API has been removed.
Deprecations
- The Pluggable SCM API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Pluggable SCM API version 2 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 3 of the API is available, and users are encouraged to use it.
- The Packages API version 1 has been deprecated in GoCD release v20.3.0. This version will be removed in GoCD release v20.6.0. Version 2 of the API is available, and users are encouraged to use it.
- The Template Config API version 6 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 2 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 3 of the API is available, and users are encouraged to use it.
- The Pipeline Comparison API version 1 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release v20.5.0. Version 2 of the API is available, and users are encouraged to use it.
- The Notification Filter API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Feeds API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0.
- The unversioned Pipeline Instance API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Status API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0. Version 1 of the API is available, and users are encouraged to use it.
- The Stage API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Job History API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release v20.4.0. Version 1 of the API is available, and users are encouraged to use it.
Changes in 20.2.0
Added
- Introduced version 7 of the Template Config API.
- Introduced version 3 of the Config Repo API.
- Introduced version 1 of the Permissions API.
- Introduced version 2 of the Pipeline Comparison API.
Removed
- The Auth Config API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Role Config API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Template Config API version 5 has been removed. Version 7 of the API is available, and users are encouraged to use it.
Deprecations
- The Template Config API version 6 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release scheduled for June 2020. Version 7 of the API is available, and users are encouraged to use it.
- The Config Repo API version 2 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release scheduled for June 2020. Version 3 of the API is available, and users are encouraged to use it.
- The Pipeline Comparison API version 1 has been deprecated in GoCD release v20.2.0. This version will be removed in GoCD release scheduled for June 2020. Version 2 of the API is available, and users are encouraged to use it.
- The Notification Filter API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Feeds API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020.
- The unversioned Pipeline Instance API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Status API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
- The Stage API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Job History API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Group Config Listing API has been deprecated in GoCD release v19.12.0. This version will be removed in GoCD release scheduled for April 2020.
- The unversioned Agent Job History API has been deprecated in GoCD release v19.12.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
Changes in 20.1.0
Added
- Introduced version 2 of the Notification Filter API.
- Introduced newer version of the Feeds API.
- Introduced version 1 of Pipeline Instance APIs.
- Introduced version 1 of Pipeline Status API.
- Introduced version 2 of the Stage API.
- Introduced version 1 of the Job History API.
- Introduced version 1 of the Job Instance API.
Removed
Deprecations
- The Notification Filter API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Feeds API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020.
- The unversioned Pipeline Instance API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
- The unversioned Pipeline Status API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
- The Stage API version 1 has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 2 of the API is available, and users are encouraged to use it.
- The unversioned Job History API has been deprecated in GoCD release v20.1.0. This version will be removed in GoCD release scheduled for April 2020. Version 1 of the API is available, and users are encouraged to use it.
Changes in 19.12.0
Added
- Introduced version 1 of the Agent Job History API.
- Introduced version 6 of the Template Config API.
- Introduced version 1 of the Comment on pipeline instance.
Removed
- The unversioned Cancel Stage API has been removed. Version 1 of the API is available, and users are encouraged to use it.
Deprecations
- The unversioned Pipeline Group Config Listing API has been deprecated in GoCD release v19.12.0. This version will be removed in GoCD release scheduled for Mar 2020.
- The unversioned Agent Job History API has been deprecated in GoCD release v19.12.0. This version will be removed in GoCD release scheduled for Mar 2020. Version 1 of the API is available, and users are encouraged to use it.
- The Auth Config API version 1 has been deprecated in GoCD release v19.11.0. This version will be removed in GoCD release scheduled for Jan 2020. Version 2 of the API is available, and users are encouraged to use it.
- The Role Config API version 2 has been deprecated in GoCD release v19.11.0. This version will be removed in GoCD release scheduled for Jan 2020. Version 3 of the API is available, and users are encouraged to use it.
- The Template Config API version 5 has been deprecated in GoCD release v19.12.0. This version will be removed in GoCD release scheduled for March 2020. Version 6 of the API is available, and users are encouraged to use it.
Changes in 19.11.0
Added
- Introduced version 3 of the Role Config API.
- Introduced version 2 of the Auth Config API.
- Introduced Extract Template API.
- Introduced version 1 of Site urls API.
- Introduced version 1 of Artifact Config API.
- Introduced version 1 of Default Job Timeout API.
Removed
- The unversioned Cancel Stage API has been removed. Version 1 of the API is available, and users are encouraged to use it.
Deprecations
- The Auth Config API version 1 has been deprecated in GoCD release v19.11.0. This version will be removed in GoCD release scheduled for Jan 2020. Version 2 of the API is available, and users are encouraged to use it.
- The Role Config API version 2 has been deprecated in GoCD release v19.11.0. This version will be removed in GoCD release scheduled for Jan 2020. Version 3 of the API is available, and users are encouraged to use it.
Changes in 19.10.0
Added
- Introduced version 10 of Pipeline Config API. Version 10 of API removes support for
propertiesobject in the pipeline config, adds support for theignore_for_schedulingflag for dependency materials and allows fetch and update of the pipelinegroupattribute. - Introduced version 5 of Template Config API. This was done to remove support for
propertiesobject in the template config. - Introduced version 2 of the Materials API. This was done to re-enable support for the
uuidparameter for Notifying SVN materials, and add theignore_for_schedulingflag for dependency materials. - Introduced version 1 of the Pipeline Comparison API.
Removed
- The Plugin Info API version 5 has been removed. Version 6 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 7 has been removed. Version 10 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 8 has been removed. Version 10 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 9 has been removed. Version 10 of the API is available, and users are encouraged to use it.
- The Template Config API version 4 has been removed. Version 5 of the API is available, and users are encouraged to use it.
Deprecations
- The unversioned Cancel Stage API has been deprecated in GoCD release v19.8.0. This version will be removed in GoCD release scheduled for Nov 2019. Version 1 of the API is available, and users are encouraged to use it.
- The Materials API version 1 has been deprecated in GoCD release v19.10.0. This version will be removed in GoCD release scheduled for Apr 2020. Version 2 of the API is available, and users are encouraged to use it.
Changes in 19.9.0
Added
- Introduced version 3 of Environment Config API
- Introduced version 6 of Agents API
Removed
- We have removed the following APIs as a part of this pull request
- The Environment Config API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The Agents API version 4 has been removed. Version 6 of the API is available, and users are encouraged to use it.
- The Agents API version 5 has been removed. Version 6 of the API is available, and users are encouraged to use it.
- The unversioned Materials API has been removed. Version 1 of the API is available, and users are encouraged to use it.
Deprecations
- The Plugin Info API version 5 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 6 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 7 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 9 of the API is available, and users are encouraged to use it.
- Unversioned get all materials API has been deprecated in favor of get all materials API v1. This version will be removed in a release scheduled for Oct 2019.
- The Pipeline Config API version 8 has been deprecated in GoCD release v19.8.0. This version will be removed in GoCD release scheduled for Nov 2019. Version 9 of the API is available, and users are encouraged to use it.
- The unversioned Cancel Stage API has been deprecated in GoCD release v19.8.0. This version will be removed in GoCD release scheduled for Nov 2019. Version 1 of the API is available, and users are encouraged to use it.
Changes in 19.8.0
Added
- Introduced version 1 of Mailserver Config API
- Introduced version 9 of Pipeline Config API.
- It is now possible to omit the version number by specifying
Accept: application/vnd.go.cd+json. This will render the latest version of the API endpoint being invoked. - Introduced version 1 of Stage Cancel API.
- Introduced version 2 of Pluggable SCM API to add support for Delete Pluggable SCM.
Removed
- The Pipeline Config API version 6 has been removed. Version 9 of the API is available, and users are encouraged to use it.
- The Config Repo API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- Cookie/Session authentication should no longer be used for API authentication. Users should either use Basic Authentication or Token based authentication for any API requests going forward.
- Removed support for the Properties API. See this pull request for details.
Deprecations
- The Plugin Info API version 5 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 6 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 7 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 9 of the API is available, and users are encouraged to use it.
- Unversioned get all materials API has been deprecated in favor of get all materials API v1. This version will be removed in a release scheduled for Oct 2019.
- The Pipeline Config API version 8 has been deprecated in GoCD release v19.8.0. This version will be removed in GoCD release scheduled for Nov 2019. Version 9 of the API is available, and users are encouraged to use it.
- The unversioned Cancel Stage API has been deprecated in GoCD release v19.8.0. This version will be removed in GoCD release scheduled for Nov 2019. Version 1 of the API is available, and users are encouraged to use it.
Changes in 19.7.0
No changes. 19.7.0 was primarily a bugfix release.
Deprecations
- The Pipeline Config API version 6 has been deprecated in GoCD release v19.6.0. This version will be removed in GoCD release scheduled for Aug 2019. Version 8 of the API is available, and users are encouraged to use it.
- The Config Repo API version 1 has been deprecated in GoCD release v19.6.0. This version will be removed in GoCD release scheduled for Aug 2019. Version 2 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 5 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 6 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 7 has been deprecated in GoCD release v19.7.0. This version will be removed in GoCD release scheduled for Oct 2019. Version 8 of the API is available, and users are encouraged to use it.
- Unversioned get all materials API has been deprecated in favor of get all materials API v1. This version will be removed in a release scheduled for Oct 2019.
Changes in 19.6.0
Added
- Introduced version 1 of Materials API.
- Introduced version 1 of Secret Configs API.
- Introduced version 6 of Plugin Info API.
- Introduced version 1 of Backup Config API.
Removed
- The Stage History unversioned API has been removed. Version 1 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 4 has been removed. Version 6 of the API is available, and users are encouraged to use it.
Deprecations
- The Pipeline Config API version 6 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 8 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 5 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 6 of the API is available, and users are encouraged to use it.
- Unversioned Materials API has been deprecated in favor of Materials API v1. This version will be removed in a release scheduled for October 2019.
Changes in 19.5.0
Removed
- The Dashboard API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
Deprecations
- Unversioned get stage history API has been deprecated in favor of get stage history API v1. This version will be removed in a release scheduled for July 2019.
- The Plugin Info API version 4 has been deprecated. This version will be removed in a release scheduled for July 2019. Version 5 of the API is available, and users are encouraged to use it.
- The ConfigRepo API version 1 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 2 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 6 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 7 of the API is available, and users are encouraged to use it.
Changes in 19.4.0
Added
- Introduced version 2 of Config Repo API.
- Introduced version 7 of Pipeline Config API.
Removed
No removals this release.
Deprecations
- Unversioned get stage history API has been deprecated in favor of get stage history API v1. This version will be removed in a release scheduled for July 2019.
- The Dashboard API version 2 has been deprecated. This version will be removed in a release scheduled for June 2019. Version 3 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 4 has been deprecated. This version will be removed in a release scheduled for July 2019. Version 5 of the API is available, and users are encouraged to use it.
- The ConfigRepo API version 1 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 2 of the API is available, and users are encouraged to use it.
- The Pipeline Config API version 6 has been deprecated. This version will be removed in a release scheduled for August 2019. Version 7 of the API is available, and users are encouraged to use it.
Changes in 19.3.0
Added
- Introduced version 2 of Backup API.
- Introduced version 5 of Plugin Info API.
- Introduced version 2 of Elastic Agent Profiles API.
- Introduced version 1 of Cluster Profiles API.
- Introduced version 1 of Stage History API.
- Introduced version 5 of Agents API.
Removed
- The Dashboard API version 1 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- The System Admins API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Roles API version 1 has been removed. Version 2 of the API is available, and users are encouraged to use it.
- The Users API version 2 has been removed. Version 3 of the API is available, and users are encouraged to use it.
- Unversioned Get Stage Instance API has been removed in favor of Get Stage Instance API v1.
Deprecations
- Unversioned get stage history API has been deprecated in favor of get stage history API v1. This version will be removed in a release scheduled for July 2019.
- The Dashboard API version 2 has been deprecated. This version will be removed in a release scheduled for June 2019. Version 3 of the API is available, and users are encouraged to use it.
- The Plugin Info API version 4 has been deprecated. This version will be removed in a release scheduled for July 2019. Version 5 of the API is available, and users are encouraged to use it.
Changes in 19.2.0
Added
- This version adds support for API tokens. See bearer token authentication for using tokens to authenticate with the GoCD server.
Removed
No removals this release.
Deprecations
- The Dashboard API v1 has been deprecated. This version of the API will be removed in a release scheduled for March 2019. Version 2 of the API is available, and users are encouraged to use it.
- Unversioned Get Stage Instance API has been deprecated in favor of Get Stage Instance API v1. This version will be removed in a release scheduled for April 2019.
- The Users API v2 has been deprecated. This version of the API will be removed in a release scheduled for April 2019. Version 3 of the API is available, and users are encouraged to use it.
- The System Admins API v1 has been deprecated. This version of the API will be removed in a release scheduled for April 2019. Version 2 of the API is available, and users are encouraged to use it.
- The Roles API v1 has been deprecated. This version of the API will be removed in a release scheduled for April 2019. Version 2 of the API is available, and users are encouraged to use it.