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.v1+json. You may access the APIs over plain text, but for security reasons we suggest that you use SSL.
API versions
It is recommended to explicitly request the version of an API via the Accept header.
Accept: application/vnd.go.cd.v1+json
Accept: application/vnd.go.cd.v2+json etc
If you specify an unsupported Accept header, GoCD will respond with the error message The url you are trying to reach appears to be incorrect.
Authentication
All APIs require you to authenticate yourself using your username and password. A cookie will also be returned as a result of the first authentication call. You may use this cookie for any further authentication attempts. If authentication fails, Go may return status codes 401, 403 or 404.
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/agents' \
-u 'username:password' \
-H 'Accept: application/vnd.go.cd.v2+json' \
Make sure to replace the
usernameandpasswordwith the username and password that you use to access the go server. The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/vnd.go.cd.v1+json; charset=utf-8
Set-Cookie: JSESSIONID=15kvus1kdrec46vk2a6jmtmo;Path=/go;Expires=Mon, 15-Jun-2015 10:16:20 GMT
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents"
},
"doc": {
"href": "https://api.gocd.org/#agents"
}
},
"_embedded": {
"agents": []
}
}
To use Basic Authentication with the Go API, simply send the username and password associated with the account.
Cookie/Session authentication
Using the cookie/session returned from the previous API call, one can make further API calls. Using a cookie will dramatically improve performance of API calls especially if go is authenticating against an external source like LDAP.
$ curl 'https://ci.example.com/go/api' \
-b 'JSESSIONID=15kvus1kdrec46vk2a6jmtmo' \
-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
Set-Cookie: JSESSIONID=15kvus1kdrec46vk2a6jmtmo;Path=/go;Expires=Mon, 15-Jun-2015 10:16:20 GMT
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents"
},
"doc": {
"href": "https://api.gocd.org/#agents"
}
},
"_embedded": {
"agents": []
}
}
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. |
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. |
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. |
Get all agents
$ curl 'https://ci.example.com/go/api/agents' \
-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/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",
"resources": ["java", "linux", "firefox"],
"environments": ["perf", "UAT"],
"build_state": "Idle"
}
]
}
}
Lists all available agents, these are agents that are present in the <agents/> tag inside cruise-config.xml and also agents that are in Pending state awaiting registration.
Available since v15.2.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.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/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",
"resources": ["java", "linux", "firefox"],
"environments": ["perf", "UAT"],
"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)
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.v4+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.v4+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": ["Dev"],
"build_state": "Idle"
}
Update some attributes of an agent.
Available since v15.2.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. |
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.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": "Deleted 1 agent(s)."
}
Deletes an agent.
Available since v15.2.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.v4+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.v4+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.
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. Updating of resources is NOT supported by elastic agents. |
resources |
Object | The resources update operation to be performed on the set of 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. |
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.v4+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.v4+json; charset=utf-8
{
"message": "Deleted 2 agent(s)."
}
Deletes a list of agents.
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'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"jobs": [
{
"agent_uuid": "5c5c318f-e6d3-4299-9120-7faff6e6030b",
"name": "upload",
"job_state_transitions": [
{
"state_change_time": 1435631497131,
"id": 539906,
"state": "Scheduled"
},
...
],
"scheduled_date": 1435631497131,
"original_job_id": null,
"pipeline_counter": 251,
"rerun": false,
"pipeline_name": "distributions-all",
"result": "Passed",
"state": "Completed",
"id": 100129,
"stage_counter": "1",
"stage_name": "upload-installers"
}
],
"pagination": {
"offset": 0,
"total": 1292,
"page_size": 10
}
}
Lists the jobs that have executed on an agent.
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]
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. |
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. |
Get all users
$ curl 'https://ci.example.com/go/api/users' \
-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/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,
"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.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": "jdoe",
"enabled": true,
"email": null,
"email_me": false,
"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.v1+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.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": true,
"email": null,
"email_me": false,
"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.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 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.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": "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.
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.
Notification Filters
The notification filters API allows the authenticated user to manage their notification filters.
The notification filter object
Available since v17.5.0.
| Attribute | Type | Description |
|---|---|---|
id |
Number | The internal ID of the notification filter. |
pipeline |
String | The pipeline name to which the notification filter should match. |
stage |
String | The stage name to which the notification filter should match. |
event |
String | The event to which the notification filter should match. |
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.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
{
"filters": [
{
"id": 10,
"pipeline": "my_pipeline",
"stage": "[Any Stage]",
"event": "Breaks",
"match_commits": true
}
]
}
Lists all notification filters for the authenticated user.
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.v1+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.v1+json; charset=utf-8
{
"filters": [
{
"id": 1,
"pipeline": "already_existed",
"stage": "[Any Stage]",
"event": "All",
"match_commits": true
},
{
"id": 2,
"pipeline": "my_pipeline",
"stage": "my_stage",
"event": "Breaks",
"match_commits": true
}
]
}
Creates a notification filter for the authenticated user.
Available since v17.5.0.
HTTP Request
POST /go/api/notification_filters
The following properties may be specified:
| Attribute | Type | Description |
|---|---|---|
pipeline |
String | The pipeline name to match. Can also be “[Any Pipeline]”. This attribute MUST be specified. |
stage |
String | The stage name to match. Can also be “[Any Stage]”. This attribute MUST be specified. |
event |
String | The event to match. Can be one of: “All”, “Passes”, “Fails”, “Breaks”, “Fixed”, “Cancelled”. This attribute MUST be specified. |
match_commits |
Boolean | Should the filter only match the user’s commits? Defaults to false if omitted. |
Returns
An array of notification filter objects representing the current set the user’s notification filters.
Delete a notification filter
$ curl 'https://ci.example.com/go/api/notification_filters/10' \
-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
{
"filters": [
]
}
Deletes a notification filter for the authenticated user.
Available since v17.5.0.
HTTP Request
DELETE /go/api/notification_filters/:id
Returns
An array of notification filter objects representing the user’s remaining notification filters.
Materials
The materials API allows users to query and notify materials in the Go configuration.
The material object
Available since v14.3.0.
| Attribute | Type | Description |
|---|---|---|
description |
String | The description of the material. |
fingerprint |
String | The fingerprint of the material. |
type |
String | The type of a material. Can be one of Git, Mercurial, Perforce, Subversion, Tfs, Pipeline, SCM. |
Get all materials
$ curl 'https://ci.example.com/go/api/config/materials' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"description": "URL: https://github.com/gocd/gocd, Branch: master",
"fingerprint": "03c8d2a131154436b6ef2d621c6f773837481aaea8c5c1bb9c0cb9b5bc64a2f1",
"type": "Git"
}
]
Lists all available materials, these are materials that are present in the in cruise-config.xml.
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'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"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
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.
Notify SVN materials
$ curl 'https://ci.example.com/go/api/material/notify/svn' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d 'uuid=svn-repository-uuid'
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8
The material is now scheduled for an update. Please check relevant pipeline(s) for status.
APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.
Available since v14.3.0.
HTTP Request
POST /go/api/material/notify/svn
The following post parameters must be specified.
| Attribute | Type | Description |
|---|---|---|
uuid |
String | The subversion repository UUID. |
Returns
A text confirmation.
Notification script
To notify Go 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
REPOS="$1"
REV="$2"
UUID=$(svnlook uuid $1)
curl 'https://ci.example.com/go/api/material/notify/svn' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d "uuid=$UUID"
Notify git materials
$ curl 'https://ci.example.com/go/api/material/notify/git' \
-u 'username:password' \
-H 'Confirm: true' \
-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: text/plain; charset=UTF-8
The material is now scheduled for an update. Please check relevant pipeline(s) for status.
APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.
Available since v14.3.0.
HTTP Request
POST /go/api/material/notify/git
The following post parameters must be specified.
| Attribute | Type | Description |
|---|---|---|
repository_url |
String | The git repository url as defined in cruise-config.xml. |
Returns
A text confirmation.
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/material/notify/git' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d "repository_url=git://git.example.com/git/funky-widgets.git"
Hosting your repository on GitHub [Enterprise]?
Available since v17.6.0.
To notify GoCD of an update to a repository via an organisation level webhook (GitHub Push Event), configure GitHub to use the webhooks api negating the need for basic authentication on each request. Polling must be turned off for the pipeline associated with this material
{server-url}/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.
Returns
A text confirmation, with the http status 202 Accepted.
Notify Mercurial materials
$ curl 'https://ci.example.com/go/api/material/notify/hg' \
-u 'username:password' \
-H 'Confirm: true' \
-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: text/plain; charset=UTF-8
The material is now scheduled for an update. Please check relevant pipeline(s) for status.
APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.
Available since v14.3.0.
HTTP Request
POST /go/api/material/notify/hg
The following post parameters must be specified.
| Attribute | Type | Description |
|---|---|---|
repository_url |
String | The Mercurial repository URL as defined in cruise-config.xml. |
Returns
A text confirmation.
Notification script
To notify Go 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/material/notify/hg' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d "repository_url=ssh://hg.example.com//hg/repos/funky-widgets"
Notify other scm materials
$ curl 'https://ci.example.com/go/api/material/notify/scm' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d "scm_name=material_name"
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: text/plain; charset=UTF-8
The material is now scheduled for an update. Please check relevant pipeline(s) for status.
APIs that notify Go Server when a commit has been made in Version Control and Go needs to trigger relevant pipelines.
Available since v14.3.0.
HTTP Request
POST /go/api/material/notify/scm
The following post parameters must be specified.
| Attribute | Type | Description |
|---|---|---|
scm_name |
String | The scm_name is the material name as defined in pipeline material page. |
Returns
A text confirmation.
Backups
The backups API allows users with administrator role to manage go server backups.
The backup object
Available since v15.2.0.
| Attribute | Type | Description |
|---|---|---|
time |
DateTime | The time of the backup. |
path |
String | The filesystem location of the backup. |
user |
Object | The user that performed this backup. |
Create a backup
$ curl 'https://ci.example.com/go/api/backups' \
-u 'username:password' \
-H 'Confirm: true' \
-H 'Accept: application/vnd.go.cd.v1+json' \
-X POST
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/#backups"
}
},
"time": "2015-08-07T10:07:19.868Z",
"path": "/var/lib/go-server/serverBackups/backup_20150807-153719",
"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"
}
},
"login_name": "username"
}
}
Create a server backup.
Available since v15.2.0.
HTTP Request
POST /go/api/backups
Returns
A new backup object.
Pipeline Groups
The pipeline groups allows users to list pipeline groups along with the pipelines, stages and materials for each pipeline.
Config listing
$ curl 'https://ci.example.com/go/api/config/pipeline_groups' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"pipelines": [
{
"stages": [
{
"name": "up42_stage"
}
],
"name": "up42",
"materials": [
{
"description": "URL: https://github.com/gocd/gocd, Branch: master",
"fingerprint": "2d05446cd52a998fe3afd840fc2c46b7c7e421051f0209c7f619c95bedc28b88",
"type": "Git"
}
],
"label": "${COUNT}"
}
],
"name": "first"
}
]
This API is built primarily to support rendering of value stream mapping. As such the information rendered in the configuration is kept to a minimum.
Available since v14.3.0.
HTTP Request
GET /go/api/config/pipeline_groups
Returns
A list of pipeline groups, pipelines in each group, stages and materials in each pipeline.
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.
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.
Pipelines
The pipelines API allows users to view pipeline information and operate on it.
Get pipeline instance
$ curl 'http://ci.example.com/go/api/pipelines/PipelineName/instance/1' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"build_cause": {
"approver": "",
"material_revisions": [
{
"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"
}
],
"material": {
"description": "URL: https://github.com/gocd/gocd, Branch: master",
"fingerprint": "61e2da369d0207a7ef61f326eed837f964471b35072340a03f8f55d993afe01d",
"type": "Git",
"id": 4
},
"changed": true
}
],
"trigger_forced": false,
"trigger_message": "modified by Pick E Reader <pick.e.reader@example.com>"
},
"name": "PipelineName",
"natural_order": 1,
"can_run": false,
"comment": null,
"stages": [
{
"name": "stage1",
"approved_by": "changes",
"jobs": [
{
"name": "jsunit",
"result": "Passed",
"state": "Completed",
"id": 1,
"scheduled_date": 1398332981981
}
],
"can_run": false,
"result": "Passed",
"approval_type": "success",
"counter": "1",
"id": 1,
"operate_permission": false,
"rerun_of_counter": null,
"scheduled": true
}
],
"counter": 1,
"id": 1,
"preparing_to_schedule": false,
"label": "14.1.0.1-b14a81825d081411993853ea5ea45266ced578b4"
}
Gets pipeline instance object.
Available since v15.1.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/instance/:pipeline_counter
Returns
A pipeline instance object.
Get pipeline history
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/history/0' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"pipelines": [
{
"build_cause": {
"approver": "anonymous",
"material_revisions": [
{
"modifications": [
{
"email_address": null,
"id": 1,
"modified_time": 1434957613000,
"user_name": "Pick E Reader <pick.e.reader@example.com>",
"comment": "my hola mundo changes",
"revision": "c194b49db102b705ebc13e604e490ae13ac92d96"
}
],
"material": {
"description": "URL: https://github.com/gocd/gocd, Branch: master",
"fingerprint": "f6e7a3899c55e1682ffb00383bdf8f882bcee2141e79a8728254190a1fddcf4f",
"type": "Git",
"id": 1
},
"changed": false
}
],
"trigger_forced": true,
"trigger_message": "Forced by anonymous"
},
"name": "pipeline1",
"natural_order": 11,
"can_run": true,
"comment": null,
"stages": [
{
"name": "stage1",
"approved_by": "admin",
"jobs": [
{
"name": "job1",
"result": "Failed",
"state": "Completed",
"id": 13,
"scheduled_date": 1436172201081
}
],
"can_run": true,
"result": "Failed",
"approval_type": "success",
"counter": "1",
"id": 13,
"operate_permission": true,
"rerun_of_counter": null,
"scheduled": true
}
],
"counter": 11,
"id": 13,
"preparing_to_schedule": false,
"label": "11"
},
{
"build_cause": {
"approver": "anonymous",
"material_revisions": [
{
"modifications": [
{
"email_address": null,
"id": 1,
"modified_time": 1434957613000,
"user_name": "Pick E Reader <pick.e.reader@example.com>",
"comment": "my hola mundo changes",
"revision": "c194b49db102b705ebc13e604e490ae13ac92d96"
}
],
"material": {
"description": "URL: https://github.com/gocd/gocd, Branch: master",
"fingerprint": "f6e7a3899c55e1682ffb00383bdf8f882bcee2141e79a8728254190a1fddcf4f",
"type": "Git",
"id": 1
},
"changed": false
}
],
"trigger_forced": true,
"trigger_message": "Forced by anonymous"
},
"name": "pipeline1",
"natural_order": 10,
"can_run": true,
"comment": null,
"stages": [
{
"name": "stage1",
"approved_by": "admin",
"jobs": [
{
"name": "job1",
"result": "Passed",
"state": "Completed",
"id": 12,
"scheduled_date": 1436172122024
}
],
"can_run": true,
"result": "Passed",
"approval_type": "success",
"counter": "1",
"id": 12,
"operate_permission": true,
"rerun_of_counter": null,
"scheduled": true
}
],
"counter": 10,
"id": 12,
"preparing_to_schedule": false,
"label": "10"
}
],
"pagination": {
"offset": 0,
"total": 2,
"page_size": 10
}
}
The pipeline history allows users to list pipeline instances. Supports pagination using offset which tells the API how many instances to skip.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/history
With pagination
GET /go/api/pipelines/:pipeline_name/history[/:offset]
Returns
An array of pipeline instances.
Get pipeline status
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/status' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"locked": false,
"paused": true,
"schedulable": false
}
The pipeline status allows users to check if the pipeline is paused, locked and schedulable.
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 'Confirm: true' \
-X POST \
-d 'pauseCause=take some rest'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Pause the specified pipeline.
Available since v14.3.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/pause
The following post parameters must be specified.
| Attribute | Type | Description |
|---|---|---|
pauseCause |
String | Reason for pausing the pipeline. |
Returns
Nothing.
Unpause a pipeline
$ curl 'https://ci.example.com/go/api/pipelines/pipeline1/unpause' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Unpause the specified pipeline.
Available since v14.3.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/unpause
Returns
Nothing.
Releasing a pipeline lock
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/releaseLock' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
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 v14.3.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/releaseLock
Returns
A text confirmation.
Scheduling pipelines
$ curl 'http://ci.example.com/go/api/pipelines/pipeline1/schedule' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 202 Accepted
Content-Type: text/html; charset=utf-8
Request to schedule pipeline pipeline1 accepted
Scheduling allows user to trigger a specific pipeline.
Available since v14.3.0.
HTTP Request
POST /go/api/pipelines/:pipeline_name/schedule
You may optionally submit specific materials information and environment variables in order to schedule the pipeline with the specified set of materials and parameterize it with the specified environment variables.
| Post Data | Desciption |
|---|---|
| no parameter | Triggers a new instance of the specified pipeline with the latest revision of all materials. |
materials[svn_material]=3456 |
Triggers a new instance of the specified pipeline with revision 3456 of the material whose materialName attribute is svn_version. |
materials[repo-name:pkg-name]=gcc-4.4.7-3.el6.x86_64 |
Triggers a new instance of the specified pipeline with revision gcc-4.4.7-3.el6.x86_64 of the rpm package material. |
materials[svn_material]=3456&materials[upstream_foo]=upstream_foo/2/dist/1 |
Triggers a new instance of the specified pipeline by specifying multiple materials. |
variables[ENV_VAR_1]=value1 |
Triggers a new instance of the specified pipeline with a parameterized environment variable. Pipeline-level environment variable ENV_VAR_1 will be set to value1. |
materials[svn_material]=3456&variables[ENV_VAR_1]=value1&variables[ENV_VAR_2]=value2 |
Triggers a new instance of the specified pipeline with revision 3456 of the material and two parameterized environment variables, ENV_VAR_1 and ENV_VAR_2. |
secure_variables[PASSWORD]=new_password |
Triggers a new instance of the specified pipeline with a parameterized secure environment variable. Pipeline-level secure environment variable PASSWORD will be set to new_password. |
Returns
A text confirmation.
Stages
The stages API allows users to view stage information and operate on it.
Cancel stage
$ curl 'https://ci.example.com/go/api/stages/myPipeline/myStages/cancel' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Stage cancelled successfully.
Cancel an active stage of a specified stage.
Available since v14.3.0.
HTTP Request
POST /go/api/stages/:pipeline_name/:stage_name/cancel
Returns
A text confirmation.
Get stage Instance
$ curl 'https://ci.example.com/go/api/stages/myPipeline/myStages/instance/1/1' \
-u 'username:password'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"name": "defaultStage",
"clean_working_directory": false,
"approved_by": "changes",
"jobs": [
{
"agent_uuid": "278fb0b6-d3b8-47e1-9443-67f26bfb5c15",
"name": "defaultJob",
"job_state_transitions": [
{
"state_change_time": 1436509518752,
"id": 1,
"state": "Scheduled"
},
{
"state_change_time": 1436509524491,
"id": 2,
"state": "Assigned"
},
{
"state_change_time": 1436509534639,
"id": 3,
"state": "Preparing"
},
{
"state_change_time": 1436509542522,
"id": 4,
"state": "Building"
},
{
"state_change_time": 1436509642582,
"id": 5,
"state": "Completing"
},
{
"state_change_time": 1436509642631,
"id": 6,
"state": "Completed"
}
],
"scheduled_date": 1436509518752,
"original_job_id": null,
"pipeline_counter": null,
"rerun": false,
"pipeline_name": null,
"result": "Passed",
"state": "Completed",
"id": 1,
"stage_counter": null,
"stage_name": null
}
],
"pipeline_counter": 1,
"pipeline_name": "mypipeline",
"approval_type": "success",
"result": "Passed",
"counter": 1,
"id": 1,
"rerun_of_counter": null,
"fetch_materials": true,
"artifacts_deleted": false
}
Gets stage instance object.
Available since v15.1.0.
HTTP Request
GET /go/api/stages/:pipeline_name/:stage_name/instance/:pipeline_counter/:stage_counter
Returns
A stage instance object.
Get stage history
$ curl 'https://ci.example.com/go/api/stages/myPipeline/defaultStage/history' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"stages": [
{
"name": "defaultStage",
"approved_by": "admin",
"jobs": [
{
"name": "defaultJob",
"result": "Cancelled",
"state": "Completed",
"id": 3,
"scheduled_date": 1436509881002
}
],
"pipeline_counter": 3,
"pipeline_name": "mypipeline",
"result": "Cancelled",
"approval_type": "success",
"id": 3,
"counter": "1",
"rerun_of_counter": null
},
{
"name": "defaultStage",
"approved_by": "admin",
"jobs": [
{
"name": "defaultJob",
"result": "Cancelled",
"state": "Completed",
"id": 2,
"scheduled_date": 1436509783931
}
],
"pipeline_counter": 2,
"pipeline_name": "mypipeline",
"result": "Cancelled",
"approval_type": "success",
"id": 2,
"counter": "1",
"rerun_of_counter": null
},
{
"name": "defaultStage",
"approved_by": "changes",
"jobs": [
{
"name": "defaultJob",
"result": "Passed",
"state": "Completed",
"id": 1,
"scheduled_date": 1436509518752
}
],
"pipeline_counter": 1,
"pipeline_name": "mypipeline",
"result": "Passed",
"approval_type": "success",
"id": 1,
"counter": "1",
"rerun_of_counter": null
}
],
"pagination": {
"offset": 0,
"total": 3,
"page_size": 10
}
}
The stage history allows users to list stage instances of specified stage. Supports pagination using offset which tells the API how many instances to skip.
Available since v14.3.0.
HTTP Request
GET /go/api/stages/:pipeline_name/:stage_name/history
With pagination
GET /go/api/stages/:pipeline_name/:stage_name/history[/:offset]
Returns
An array of stage instances.
Jobs
The jobs API allows users to view job information.
Get scheduled jobs
$ curl 'https://ci.example.com/go/api/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
<scheduledJobs>
<job name="job1" id="6">
<link rel="self" href="https://ci.example.com/go/tab/build/detail/mypipeline/5/defaultStage/1/job1"/>
<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"/>
<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 v14.3.0.
HTTP Request
GET /go/api/jobs/scheduled.xml
Returns
An array of scheduled job instances.
Get job history
$ curl 'https://ci.example.com/go/api/jobs/mypipeline/defaultStage/job1/history' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"jobs": [
{
"agent_uuid": null,
"name": "job1",
"job_state_transitions": [],
"scheduled_date": 1436519914378,
"original_job_id": null,
"pipeline_counter": 5,
"rerun": false,
"pipeline_name": "mypipeline",
"result": "Unknown",
"state": "Scheduled",
"id": 6,
"stage_counter": "1",
"stage_name": "defaultStage"
},
{
"agent_uuid": "278fb0b6-d3b8-47e1-9443-67f26bfb5c15",
"name": "job1",
"job_state_transitions": [],
"scheduled_date": 1436519733253,
"original_job_id": null,
"pipeline_counter": 4,
"rerun": false,
"pipeline_name": "mypipeline",
"result": "Passed",
"state": "Completed",
"id": 4,
"stage_counter": "1",
"stage_name": "defaultStage"
}
],
"pagination": {
"offset": 0,
"total": 2,
"page_size": 10
}
}
The job history allows users to list job instances of specified job. Supports pagination using offset which tells the API how many instances to skip.
Available since v14.3.0.
HTTP Request
GET /go/api/jobs/:pipeline_name/:stage_name/:job_name/history
With pagination
GET /go/api/jobs/:pipeline_name/:stage_name/:job_name/history[/:offset]
Returns
An array of jobs instances.
Properties
The properties API allows managing of job properties.
Get all job properties
$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName' \
-u 'username:password'
The above command returns CSV structure like this (indented for readability):
cruise_agent, cruise_timestamp_01_scheduled, cruise_timestamp_02_assigned
myLocalAgent, 2015-07-09T11:59:08+05:30, 2015-07-09T11:59:16+05:30
Lists all job properties.
Available since v14.3.0.
HTTP Request
GET /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name
Returns
CSV list containing property names and their corresponding value.
Get one property
$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName/cruise_agent' \
-u 'username:password'
The above command returns CSV structure like this:
Gets a property by its name.
cruise_agent
myLocalAgent
Available since v14.3.0.
HTTP Request
GET /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/:property_name
Returns
Property name and its value.
Get historical properties
$ curl 'http://ci.example.com/go/properties/search?pipelineName=PipelineName&stageName=StageName&jobName=JobName&limitPipeline=latest&limitCount=2' \
-u 'username:password'
The above command returns CSV structure like this:
cruise_agent,cruise_job_duration,cruise_job_id,cruise_job_result,cruise_pipeline_counter,cruise_pipeline_label,cruise_stage_counter,cruise_timestamp_01_scheduled,cruise_timestamp_02_assigned,cruise_timestamp_03_preparing,cruise_timestamp_04_building,cruise_timestamp_05_completing,cruise_timestamp_06_completed
myLocalAgent,0,13,Passed,8,4f9e580347b2e259fe030a775771359cdc984346,1,2015-07-07T09:44:27+05:30,2015-07-07T09:44:34+05:30,2015-07-07T09:44:44+05:30,2015-07-07T09:44:46+05:30,2015-07-07T09:44:46+05:30,2015-07-07T09:44:46+05:30
myLocalAgent,0,14,Passed,9,4f9e580347b2e259fe030a775771359cdc984346,1,2015-07-07T10:17:37+05:30,2015-07-07T10:17:45+05:30,2015-07-07T10:17:55+05:30,2015-07-07T10:17:56+05:30,2015-07-07T10:17:56+05:30,2015-07-07T10:17:56+05:30
Available since v14.3.0.
HTTP Request
GET /go/properties/search?pipelineName=:pipeline_name&stageName=:stage_name&jobName=:job_name&limitPipeline=:pipeline_counter&limitCount=:number
Returns
Job properties as CSV.
Create property
$ curl 'http://ci.example.com/go/properties/PipelineName/541/StageName/1/JobName/PropertyName' \
-u 'username:password' \
-H 'Confirm: true' \
-X POST \
-d 'value=PropertyValue'
The above command defines a property ‘PropertyName’ for ‘PipelineName/541/StageName/1/JobName’ and returns the following response:
Property 'PropertyName' created with value 'PropertyValue'
Available since v14.3.0.
Defines a property on a specific job instance.
HTTP Request
POST /go/properties/:pipeline_name/:pipeline_counter/:stage_name/:stage_counter/:job_name/:property_name
The following post parameter must be specified :
| Attribute | Type | Description |
|---|---|---|
value |
String | The value of property. |
Returns
An acknowledgement that the property was created.
Configuration
The configuration API allows users with administration role to view and manage configuration.
List all modifications
$ curl 'https://ci.example.com/go/api/config/revisions' \
-u 'username:password'
The above command returns JSON structured like this:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
[
{
"md5": "893d30ab646489d882f2350b10f47d0e",
"commitSHA": "d2f9091145e2e4b3b22d938c4819610467ae20c1",
"username": "admin",
"goEdition": "OpenSource",
"time": 1436253610465,
"schemaVersion": 75,
"goVersion": "N/A"
},
{
"md5": "a2285d3304a51508c88e5479e327553c",
"commitSHA": "f27b48594645c9f15f55bb56d0100dd60e4cbacc",
"username": "admin",
"goEdition": "OpenSource",
"time": 1436253595701,
"schemaVersion": 75,
"goVersion": "N/A"
}
]
Lists the config repository modifications.
Available since v14.3.0.
HTTP Request
GET /go/api/config/revisions
Returns
An array of repository modifications.
Get repository modification diff
$ curl 'https://ci.example.com/go/api/config/diff/d2f9091145e2e4b3b22d938c4819610467ae20c1/f27b48594645c9f15f55bb56d0100dd60e4cbacc' \
-u 'username:password'
The above command returns the following response:
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
@@ -29,7 +29,7 @@
<job name="up42_job">
<tasks>
<exec command="sleep">
- <arg>40000</arg>
+ <arg>100</arg>
<runif status="passed" />
</exec>
</tasks>
Gets the diff between two config repository modifications.
Available since v14.3.0.
HTTP Request
GET /go/api/config/diff/:from_commit_sha/:to_commit_sha
Returns
The diff between two config repo modifications.
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.
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.
Feeds
The feed API allows users to view feed information.
Get all pipelines
$ curl 'https://ci.example.com/go/api/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://ci.example.com/go/api/pipelines.xml"/>
<pipeline href="https://ci.example.com/go/api/pipelines/pipeline1/stages.xml" />
<pipeline href="https://ci.example.com/go/api/pipelines/pipeline2/stages.xml" />
</pipelines>
Lists all pipelines.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines.xml
Returns
An array of pipelines.
Get feed of all stages
$ curl 'https://ci.example.com/go/api/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
<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/pipelines/mypipeline/stages.xml</id>
<author>
<name>Go</name>
</author>
<updated>2015-07-13T10:59:49+05:30</updated>
<link rel="self" href="https://ci.example.com/go/api/pipelines/mypipeline/stages.xml"/>
<link rel="next" href="https://ci.example.com/go/api/pipelines/mypipeline/stages.xml?before=6"/>
<entry>
<title><![CDATA[mypipeline(2) stage defaultStage(1) Cancelled]]></title>
<updated>2015-07-10T12:00:04+05:30</updated>
<id>https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1</id>
<author>
<name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
</author>
<link title="defaultStage Stage Detail" href="https://ci.example.com/go/api/stages/2.xml" rel="alternate" type="application/vnd.go+xml"/>
<link title="defaultStage Stage Detail" href="https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1" rel="alternate" type="text/html"/>
<link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/api/pipelines/mypipeline/2.xml" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="application/vnd.go+xml"/>
<link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/pipelines/mypipeline/2/defaultStage/1/pipeline" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" 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="cancelled" label="Cancelled" />
</entry>
<entry>
<title><![CDATA[mypipeline(1) stage defaultStage(1) Passed]]></title>
<updated>2015-07-10T11:57:22+05:30</updated>
<id>https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1</id>
<author>
<name><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></name>
</author>
<link title="defaultStage Stage Detail" href="https://ci.example.com/go/api/stages/1.xml" rel="alternate" type="application/vnd.go+xml"/>
<link title="defaultStage Stage Detail" href="https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1" rel="alternate" type="text/html"/>
<link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/api/pipelines/mypipeline/1.xml" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" type="application/vnd.go+xml"/>
<link title="mypipeline Pipeline Detail" href="https://ci.example.com/go/pipelines/mypipeline/1/defaultStage/1/pipeline" rel="http://www.thoughtworks-studios.com/ns/relations/go/pipeline" 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>
</feed>
Gets feed of all stages for the specified pipeline with links to the pipeline and stage details.
Available since v14.3.0.
HTTP Request
GET /go/api/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
<pipeline name="mypipeline" counter="1" label="1">
<link rel="self" href="https://ci.example.com/go/api/pipelines/mypipeline/1.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:1]]></id>
<scheduleTime>2015-07-10T11:55:18+05:30</scheduleTime>
<materials>
<material materialUri="https://ci.example.com/go/api/materials/405.xml" type="GitMaterial" url="URL: https://github.com/gocd/gocd" branch="master">
<modifications>
<changeset changesetUri="https://ci.example.com/go/api/materials/405/changeset/c194b49db102b705ebc13e604e490ae13ac92d96.xml">
<user><![CDATA[Pick E Reader <pick.e.reader@example.com>]]></user>
<checkinTime>2015-06-22T12:50:13+05:30</checkinTime>
<revision><![CDATA[c194b49db102b705ebc13e604e490ae13ac92d96]]></revision>
<message><![CDATA[Update README]]></message>
<file name="README" action="modified"/>
</changeset>
</modifications>
</material>
</materials>
<stages>
<stage href="https://ci.example.com/go/api/stages/1.xml"/>
</stages>
<approvedBy><![CDATA[changes]]></approvedBy>
</pipeline>
Gets XML representation of pipeline.
Available since v14.3.0.
HTTP Request
GET /go/api/pipelines/:pipeline_name/:pipeline_id.xml
Returns
A pipeline object.
Get stage
$ curl 'https://ci.example.com/go/api/stages/2.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<stage name="defaultStage" counter="1">
<link rel="self" href="https://ci.example.com/go/api/stages/2.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:stage-id:mypipeline:2:defaultStage:1]]></id>
<pipeline name="mypipeline" counter="2" label="2" href="https://ci.example.com/go/api/pipelines/mypipeline/2.xml"/>
<updated>2015-07-10T12:00:04+05:30</updated>
<result>Cancelled</result>
<state>Completed</state>
<approvedBy><![CDATA[admin]]></approvedBy>
<jobs>
<job href="https://ci.example.com/go/api/jobs/2.xml"/>
</jobs>
</stage>
Gets XML representation of stage.
Available since v14.3.0.
HTTP Request
GET /go/api/stages/:stage_id.xml
Alternate APIs
GET /go/pipelines/:pipeline:name/:pipeline_counter/:stage_name/:stage_counter.xml
or
GET /go/pipelines/:pipeline:name/:pipeline_label/:stage_name/:stage_counter.xml
Returns
A stage object.
Get job
$ curl 'https://ci.example.com/go/api/jobs/2.xml' \
-u 'username:password'
The above command returns XML structured like this:
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
<job name="defaultJob">
<link rel="self" href="https://ci.example.com/go/api/jobs/2.xml"/>
<id><![CDATA[urn:x-go.studios.thoughtworks.com:job-id:mypipeline:2:defaultStage:1:defaultJob]]></id>
<pipeline name="mypipeline" counter="2" label="2"/>
<stage name="defaultStage" counter="1" href="https://ci.example.com/go/api/stages/2.xml"/>
<result>Cancelled</result>
<state>Completed</state>
<properties>
<property name="cruise_agent"><![CDATA[INpicke.local]]></property>
<property name="cruise_job_duration"><![CDATA[0]]></property>
<property name="cruise_job_id"><![CDATA[2]]></property>
<property name="cruise_job_result"><![CDATA[Cancelled]]></property>
<property name="cruise_pipeline_counter"><![CDATA[2]]></property>
<property name="cruise_pipeline_label"><![CDATA[2]]></property>
<property name="cruise_stage_counter"><![CDATA[1]]></property>
<property name="cruise_timestamp_01_scheduled"><![CDATA[2015-07-10T11:59:43+05:30]]></property>
<property name="cruise_timestamp_02_assigned"><![CDATA[2015-07-10T11:59:52+05:30]]></property>
<property name="cruise_timestamp_03_preparing"><![CDATA[2015-07-10T12:00:02+05:30]]></property>
<property name="cruise_timestamp_06_completed"><![CDATA[2015-07-10T12:00:04+05:30]]></property>
</properties>
<agent uuid="278fb0b6-d3b8-47e1-9443-67f26bfb5c15"/>
<artifacts baseUri="https://ci.example.com/go/files/mypipeline/2/defaultStage/1/defaultJob" pathFromArtifactRoot="pipelines/mypipeline/2/defaultStage/1/defaultJob"/>
<resources/>
<environmentvariables/>
</job>
Gets XML representation of job.
Available since v14.3.0.
HTTP Request
GET /go/api/jobs/:job_id.xml
Returns
A job object.
Dashboard
The Dashboard API allows users to view dashboard information.
Get Dashboard
$ curl 'https://ci.example.com/go/api/dashboard' \
-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/dashboard"
},
"doc": {
"href": "https://api.gocd.org/current/#dashboard"
}
},
"_embedded": {
"pipeline_groups": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/config/pipeline_groups"
},
"doc": {
"href": "https://api.gocd.org/current/#pipeline-groups"
}
},
"name": "first",
"_embedded": {
"pipelines": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/pipelines/first/history"
},
"doc": {
"href": "https://api.gocd.org/current/#pipelines"
},
"settings_path": {
"href": "https://ci.example.com/go/admin/pipelines/first/general"
},
"trigger": {
"href": "https://ci.example.com/go/api/pipelines/first/schedule"
},
"trigger_with_options": {
"href": "https://ci.example.com/go/api/pipelines/first/schedule"
},
"pause": {
"href": "https://ci.example.com/go/api/pipelines/first/pause"
},
"unpause": {
"href": "https://ci.example.com/go/api/pipelines/first/unpause"
}
},
"name": "first",
"locked": true,
"pause_info": {
"paused": false,
"paused_by": null,
"pause_reason": null
},
"_embedded": {
"instances": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/pipelines/first/instance/2"
},
"doc": {
"href": "https://api.gocd.org/current/#get-pipeline-instance"
},
"history_url": {
"href": "https://ci.example.com/go/api/pipelines/first/history"
},
"vsm_url": {
"href": "https://ci.example.com/go/pipelines/value_stream_map/first/2"
},
"compare_url": {
"href": "https://ci.example.com/go/compare/first/1/with/2"
},
"build_cause_url": {
"href": "https://ci.example.com/go/pipelines/first/2/build_cause"
}
},
"label": "2",
"schedule_at": "2015-09-18T11:11:36.378Z",
"triggered_by": "admin",
"_embedded": {
"stages": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/stages/first/2/stage1/2"
},
"doc": {
"href": "https://api.gocd.org/current/#get-stage-instance"
}
},
"name": "stage1",
"status": "Building",
"previous_stage": {
"_links": {
"self": {
"href": "https://ci.example.com/go/api/stages/first/1/stage1/2"
},
"doc": {
"href": "https://api.gocd.org/current/#get-stage-instance"
}
},
"name": "stage1",
"status": "Passed"
}
},
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/stages/first/2/stage2/1"
},
"doc": {
"href": "https://api.gocd.org/current/#get-stage-instance"
}
},
"name": "stage2",
"status": "Passed"
}
]
}
}
]
}
}
]
}
}
]
}
}
Lists pipelines on Dashboard.
Available since v15.3.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.
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 |
|---|---|---|
label_template |
String | The label template to customise the pipeline instance label. Both of material names and ${COUNT} are available in the label_template. If not specified, label_template defaults to ${COUNT}. |
enable_pipeline_locking |
Boolean | Whether pipeline is locked to run single instance or not. |
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 local origin object for pipelines defined locally in cruise-config.xml or config repo origin object for the 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",
"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. |
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 o the externals will trigger the pipeline automatically or not. |
The mercurial material attributes
{
"materials": [
{
"type": "hg",
"attributes": {
"name": "api-docs",
"url": "http://username:password@hg.example.com/hg/api.go.cd",
"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. |
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
}
}
]
}
| 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. |
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 svn 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. Since v16.7.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",
"authorization": {
"roles": [
],
"users": [
]
}
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the approval on which stage will trigger. Can be one of success, manual. |
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 go 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. |
properties |
Array | The list of properties of the build from XML files or artifacts created during your build. |
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 Go 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. If not specified, the path 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": {
"run_if": [
"passed"
],
"pipeline": "upstream",
"stage": "upstream_stage",
"job": "upstream_job",
"is_source_a_file": false,
"source": "result",
"destination": "test"
}
}
]
}
| 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. |
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. |
is_source_a_file |
Boolean | Whether source is a file or directory. |
destination |
String | The path of the directory where the artifact is fetched to. |
on_cancel |
Object | The task specifies a task to execute when a stage is cancelled. |
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"
}
]
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of the artifact. Can be one of test, build. |
source |
String | The file or folder to publish to the server. |
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. |
The property object
{
"properties": [
{
"name": "coverage.class",
"source": "target/emma/coverage.xml",
"xpath": "substring-before(//report/data/all/coverage[starts-with(@type,'class')]/@value, '%')"
}
]
}
| Attribute | Type | Description |
|---|---|---|
name |
String | The name of the property. |
source |
String | The relative path to the XML file containing the data that you want to use to create the property. |
xpath |
String | The xpath that will be used to create property. |
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. Can be one of mingle, generic. |
attributes |
Object | The attributes of the tracking tool. See attributes for generic and mingle tracking tools. |
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 mingle tracking tool object
{
"attributes": {
"base_url": "https://mingle.example.com",
"project_identifier": "foobar_widgets",
"mql_grouping_conditions": "status > 'In Dev'"
}
}
| Attribute | Type | Description |
|---|---|---|
base_url |
String | The base URL of the Mingle server. |
project_identifier |
String | The project identfier can be found under the mingle project’s Project admin tab in the section titled Basic Information. |
mql_grouping_conditions |
String | The MQL string that determines the ‘passing criteria’ for cards displayed. |
The local origin object
{
"origin": {
"type": "local",
"file": "cruise-config.xml"
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of origin. |
file |
String | The name of config file. |
The config repo origin object
{
"type": "local",
"repo": {
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/repo",
"destination": null,
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": true,
"branch": "master",
"submodule_folder": null,
"shallow_clone": false
},
"revision": "0771169c7178c9850ab098b40cc17b24f3d3c7a9"
}
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of origin. |
repo |
Object | The config repository material object. |
The config repository material object
{
"type": "git",
"attributes": {
"url": "https://github.com/config-repo/repo",
"destination": null,
"filter": null,
"invert_filter": false,
"name": null,
"auto_update": true,
"branch": "master",
"submodule_folder": null,
"shallow_clone": false
},
"revision": "0771169c7178c9850ab098b40cc17b24f3d3c7a9"
}
| Attribute | Type | Description |
|---|---|---|
type |
String | The type of a material. Currently config repository supports only git materials. |
attributes |
Object | The attributes for each material type. |
revision |
revision | The material revision to fetch the configurations from. |
Get pipeline config
$ curl 'https://ci.example.com/go/api/admin/pipelines/my_pipeline' \
-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: "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}",
"enable_pipeline_locking": false,
"name": "my_pipeline",
"template": null,
"origin": {
"type": "local",
"file": "cruise-config.xml"
},
"params": [],
"environment_variables": [],
"materials": [
{
"type": "git",
"attributes": {
"url": "git@github.com:example/sample_repo.git",
"destination": "code",
"filter": {
"ignore": [
"**/*.*",
"**/*.html"
]
},
"invert_filter": false,
"name": "git",
"auto_update": true,
"branch": "master",
"submodule_folder": null,
"shallow_clone": true
}
}
],
"stages": [
{
"name": "my_stage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"approval": {
"type": "success",
"authorization": {
"roles": [],
"users": []
}
},
"environment_variables": [],
"jobs": [
{
"name": "my_job",
"run_instance_count": null,
"timeout": 0,
"environment_variables": [],
"resources": [
"Linux",
"Java"
],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"on_cancel": {
"type": "exec",
"attributes": {
"command": "ls",
"working_directory": null
}
},
"command": "sleep",
"arguments": [
"10"
],
"working_directory": null
}
}
],
"tabs": [
{
"name": "cobertura",
"path": "target/site/cobertura/*.xml"
}
],
"artifacts": [
{
"source": "target",
"destination": "result",
"type": "build"
},
{
"source": "test",
"destination": "res1",
"type": "test"
}
],
"properties": null
}
]
}
],
"tracking_tool": null,
"timer": null
}
Gets pipeline config for specified pipeline name.
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.v4+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "e064ca0fe5d8a39602e19666454b8d77"' \
-X PUT \
-d '{
"label_template": "${COUNT}",
"enable_pipeline_locking": true,
"name": "my_pipeline",
"template": null,
"materials": [
{
"type": "git",
"attributes": {
"url": "git@github.com:sample_repo/example.git",
"destination": "destination1",
"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
}
}
]
}
]
}
]
}'
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/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}",
"enable_pipeline_locking": true,
"name": "my_pipeline",
"template": null,
"origin": {
"type": "local",
"file": "cruise-config.xml"
},
"params": [],
"environment_variables": [],
"materials": [
{
"type": "git",
"attributes": {
"url": "git@github.com:sample_repo/example.git",
"destination": "destination1",
"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
}
}
],
"tabs": [],
"artifacts": [],
"properties": null
}
]
}
],
"tracking_tool": null,
"timer": null
}
Update pipeline config for specified pipeline name.
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.v4+json' \
-H 'Content-Type: application/json' \
-X POST -d '{ "group": "first",
"pipeline": {
"label_template": "${COUNT}",
"enable_pipeline_locking": true,
"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
}
}
]
}
]
}
]
}
}'
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/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}",
"enable_pipeline_locking": true,
"name": "new_pipeline",
"template": null,
"origin": {
"type": "local",
"file": "cruise-config.xml"
},
"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": 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": "never",
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
"passed"
],
"command": "ls",
"working_directory": null
}
}
],
"tabs": [],
"artifacts": [],
"properties": null
}
]
}
],
"tracking_tool": null,
"timer": null
}
Create a pipeline.
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.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": "Pipeline 'my_pipeline' was deleted successfully."
}
Deletes a pipeline from the config XML.
Available since v16.6.0.
HTTP Request
DELETE /go/api/admin/pipelines/:pipeline_name
Returns
A message confirmation if the pipeline was deleted.
Template Config
The template config API allows users with administrator role to manage template config.
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. |
Get all templates
$ curl 'https://ci.example.com/go/api/admin/templates' \
-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/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",
"_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"
}
]
}
}
]
}
}
Lists all available templates with the associated pipelines’ names.
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.v3+json'
-i
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: "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": "up42_stage",
"fetch_materials": true,
"clean_working_directory": false,
"never_cleanup_artifacts": false,
"approval": {
"type": "success",
"authorization": {
"roles": [
],
"users": [
]
}
},
"environment_variables": [
],
"jobs": [
{
"name": "up42_job",
"run_instance_count": null,
"timeout": "never",
"elastic_profile_id": "docker",
"environment_variables": [
],
"resources": [
],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
],
"on_cancel": null,
"command": "ls",
"working_directory": null
}
}
],
"tabs": [
],
"artifacts": [
],
"properties": null
}
]
}
]
}
Gets template config for specified template name.
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.v3+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": {
"command": "ls",
"working_directory": null
}
}
]
}
]
}
]
}'
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/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,
"elastic_profile_id": "elastic_profile_id",
"timeout": "never",
"environment_variables": [
],
"resources": [
],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
],
"on_cancel": null,
"command": "ls",
"working_directory": null
}
}
],
"tabs": [
],
"artifacts": [
],
"properties": null
}
]
}
]
}
Creates a template config object.
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.v3+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,
"timeout": 0,
"environment_variables": [],
"resources": [],
"tasks": [
{
"type": "exec",
"attributes": {
"command": "sleep",
"working_directory": null
}
}
]
}
]
}
]
}'
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: "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": "never",
"environment_variables": [
],
"resources": [
],
"tasks": [
{
"type": "exec",
"attributes": {
"run_if": [
],
"on_cancel": null,
"command": "sleep",
"working_directory": null
}
}
],
"tabs": [
],
"artifacts": [
],
"properties": null
}
]
}
]
}
Update template config for specified template name.
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.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 template 'template_name' was deleted successfully."
}
Deletes a template from the config XML if it is not associated with any pipeline.
Available since v16.10.0.
HTTP Request
DELETE /go/api/admin/templates/:template_name
Returns
A message confirmation if the template was deleted.
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.
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. |
agents |
Array | List of agent uuids 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.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: "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"
}
],
"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": "12345678-e2f6-4c78-123456789012"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
]
}
}
Lists all available environments.
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.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: "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"
}
],
"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": "12345678-e2f6-4c78-123456789012"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
Gets environment config for specified environment name.
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.v2+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name" : "new_environment",
"pipelines" : [
{
"name" : "up2"
}
],
"agents" : [
{
"uuid" : "12345678-e2f6-4c78-123456789012"
}
],
"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.v2+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"
}
],
"agents": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/agents/12345678-e2f6-4c78-123456789012"
},
"doc": {
"href": "https://api.gocd.org/#agents"
},
"find": {
"href": "https://ci.example.com/go/api/agents/:uuid"
}
},
"uuid": "12345678-e2f6-4c78-123456789012"
}
],
"environment_variables": [
{
"secure": false,
"name": "username",
"value": "admin"
},
{
"secure": true,
"name": "password",
"encrypted_value": "LSd1TI0eLa+DjytHjj0qjA=="
}
]
}
Creates an environment
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. |
agents |
Array | The list of agent uuids 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.v2+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.v2+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"
}
],
"agents": [
],
"environment_variables": [
]
}
Update some attributes of an environment.
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 added to this environment. |
agents |
Array | List of agent uuids 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. |
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.v2+json' \
-H 'Content-Type: application/json' \
-X PATCH \
-d '{
"pipelines": {
"add": ["up42"],
"remove": ["sample"]
},
"agents": {
"add": ["12345678-e2f6-4c78-123456789012"],
"remove": ["87654321-e2f6-4c78-123456789012"]
},
"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.v2+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"
}
],
"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": "12345678-e2f6-4c78-123456789012"
}
],
"environment_variables": [
{
"name": "GO_SERVER_URL",
"value": "https://ci.example.com/go",
"secure": false
}
]
}
Update some attributes of an environment.
Available since v16.10.0.
HTTP Request
PATCH /go/api/admin/environments/:environment_name
Atleast 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"
]
},
"agents": {
"add": [
"agent05",
"agent02"
],
"remove": [
"agent01"
]
},
"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. |
agents |
Object | The agents update operation to be performed on the set of agents. |
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 agent-update operation attributes
{
"add": [
"agent05",
"agent02"
],
"remove": [
"agent01"
]
}
| Attribute | Type | Description |
|---|---|---|
add |
Array | The list of agents which needs to be added to the specified environment. |
remove |
Array | The list of agents 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.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": "Environment 'my_environment' was deleted successfully."
}
Deletes an environment.
Available since v16.7.0.
HTTP Request
DELETE /go/api/admin/environments/:environment_name
Returns
A message confirmation if the environment was deleted.
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 v16.11.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | The identifier of the elastic agent profile. |
plugin_id |
String | The plugin identifier of the elastic agent profile. |
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.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/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",
"plugin_id": "cd.go.contrib.elastic-agent.docker"
}
]
}
}
Lists all available elastic agent profiles.
Available since v16.11.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.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/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",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"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 v16.11.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.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "unit-tests",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"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.v1+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",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"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 v16.11.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.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"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.v1+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",
"plugin_id": "cd.go.contrib.elastic-agent.docker",
"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 v16.11.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.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": "Elastic agent profile 'unit-test' was deleted successfully."
}
Deletes the profile.
Available since v16.11.0.
HTTP Request
DELETE /go/api/elastic/profiles/:profile_id
Returns
A message if the elastic agent profile is deleted or not.
Plugin Info
The plugin info API allows users with administrator role to fetch information about installed plugins.
The plugin info object
Available since v16.7.0.
| Attribute | Type | Description |
|---|---|---|
id |
String | Plugin unique identifier. |
name |
String | Name of the plugin. |
display_name |
String | Plugin display name to be used in views. |
version |
String | The version of the plugin. |
type |
String | The type of the plugin. Can be one of authentication, notification, package-repository, task, scm, elastic. |
pluggable_instance_settings |
Object | List of pluggable_instance_settings settings required to configure a pluggable instance e.g PluggableTask, PluggableSCM. |
image |
Object | The plugin icon for the specific plugin. This is currently only supported by elastic agent plugins. Since v16.12.0. |
The pluggable_instance_settings object
{
"pluggable_instance_settings": {
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true,
"part_of_identity": false
}
}
],
"view": {
"template": "<div>Plugin view template</div>"
}
}
}
| Attribute | Type | Description |
|---|---|---|
configurations |
Array | List of configurations required to configure a pluggable instance. |
view |
Object | The view contains the Angular view template. |
The Image Object
{
"content_type": "image/svg+xml",
"data": "...."
}
| Attribute | Type | Description |
|---|---|---|
content_type |
String | A valid content type for the image. Please make sure the content type is supported by most browsers. |
data |
String | A base-64 encoded (single-line non-chunking) byte array of the byte-sequence that composes the image. |
The plugin info configurations object
{
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true,
"part_of_identity": false
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | Describes the configuration key. |
metadata |
Object | Metadata for the configuration property. For plugins of types authentication, notification, task and scm, the metadata consists of attributes secure, required and part_of_identity. The attributes for package-repository and elastic 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 elastic configurations object
{
"configurations": [
{
"key": "Image",
"metadata": {
"secure": false,
"required": true
}
}
]
}
| Attribute | Type | Description |
|---|---|---|
key |
String | Describes the configuration key for a elastic agent 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. |
Get all plugin info
$ curl 'https://ci.example.com/go/api/admin/plugin_info' \
-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.v1+json; charset=utf-8
ETag: "3924a894cf0e5bef02abe9de0df3bb84"
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_info"
},
"doc": {
"href": "https://api.gocd.org/#plugin-info"
}
},
"_embedded": {
"plugin_info": [
{
"_links": {
"self": {
"href": "https://ci.example.com/go/api/admin/plugin_info/plugin_id"
},
"doc": {
"href": "https://api.gocd.org/#plugin-info"
},
"find": {
"href": "https://ci.example.com/go/api/admin/plugin_info/:id"
}
},
"id": "plugin_id",
"name": "SCM Plugin",
"display_name": "SCM Plugin For HG",
"version": "1.2.3",
"type": "scm"
}
]
}
}
Lists all available plugin info.
Available since v16.7.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.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: "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",
"name": "My SCM Plugin",
"display_name": "SCM Plugin For HG",
"version": "1.2.3",
"type": "scm",
"pluggable_instance_settings": {
"configurations": [
{
"key": "url",
"metadata": {
"secure": false,
"required": true,
"part_of_identity": true
}
},
{
"key": "username",
"metadata": {
"secure": false,
"required": false,
"part_of_identity": false
}
},
{
"key": "password",
"metadata": {
"secure": true,
"required": false,
"part_of_identity": false
}
}
],
"view": {
"template": "<div>Plugin view template </div>"
}
}
}
Gets plugin info for a specified plugin id.
Available since v16.7.0.
HTTP Request
GET /go/api/admin/plugin_info/:id
Returns
The plugin info object.
SCMs
The pluggable SCM API 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. |
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.v1+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/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"
}
}
]
}
}
Lists all available pluggable scm materials, these are materials that are present in the in cruise-config.xml.
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.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/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,
"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.
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.v1+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.v1+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,
"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.
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.v1+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.v1+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,
"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.
Available since v16.7.0.
HTTP Request
PUT /go/api/admin/scms/:material_name
Returns
The updated SCM object.
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.
Packages
The package definition API 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.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/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.
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.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: "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.
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.v1+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.v1+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.
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.v1+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.v1+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.
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.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 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/package/:package_id
Returns
A message confirmation if the package was deleted.
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. |
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.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/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",
"properties": [
{
"key": "Url",
"value": "ldap://ldap.server.url"
}
]
}
]
}
}
Lists all available authorization configurations.
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.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/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",
"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.
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.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"id": "ldap",
"plugin_id": "cd.go.authentication.ldap",
"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.v1+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",
"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
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.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"plugin_id": "cd.go.authentication.ldap",
"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.v1+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",
"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.
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.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 security auth config 'ldap' was deleted successfully."
}
Deletes the authorization configuration.
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.
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. |
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.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/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"]
}
},
{
"_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"
}
]
}
}
]
}
}
Lists all available roles which includes gocd role and plugin role.
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.v1+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"]
}
}
]
}
}
List all available roles of specified type.
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.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/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"
}
]
}
Gets role for specified role name.
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.v1+json' \
-H 'Content-Type: application/json' \
-X POST -d '{
"name": "new-role",
"type": "gocd",
"attributes" : {
"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: "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"]
}
}
Create a gocd role. A gocd role is a group of users having same permissions in go.
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.v1+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"
}
]
}
}'
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/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"
}
]
}
}
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.
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.v1+json' \
-H 'Content-Type: application/json' \
-H 'If-Match: "cbc5f2d5b9c13a2cc1b1efb3d8a6155d"' \
-X PUT \
-d '{
"name": "spacetiger",
"type": "gocd",
"attributes": {
"users": ["alice"]
}
}'
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/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" ]
}
}
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.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 plugin role config 'blackbird' was deleted successfully."
}
Deletes the role.
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.
Errors
Go CD 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. |