NAV
Switch version:

Package Repository Material Plugins

Extension Information
Availability GoCD version 14.4.0 onwards
Extension Name package-repository
Extension API Version 1.0

The Package Repository extension endpoint allows plugin authors to extend GoCD and integrate it package repositories.

GoCD’s user documentation has an overview of package repository material plugins. Please see that.

A sample package repository material plugin - YUM

A skeleton package repository material plugin

Requests from the GoCD server

In order to implement a SCM extension endpoint the following messages must be implemented by the plugin.

Repository Configuration

This message is sent by the server, when it wants to know what properties need to be stored in the configuration, for this plugin and this repository. It also uses this information to create a view, for the user to provide information about the repository.

The plugin will receive a request with following information.

Request name

repository-configuration

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

The server will not provide request body.

Example response body

{
  "REPO_URL": {
    "display-name": "Repository URL",
    "display-order": "0"
  },
  "USERNAME": {
    "part-of-identity": false,
    "required": false,
    "display-name": "User",
    "display-order": "1"
  },
  "PASSWORD": {
    "secure": true,
    "part-of-identity": false,
    "required": false,
    "display-name": "Password",
    "display-order": "2"
  }
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to return an object containing the configuration property along with repository configuration object

Package Configuration

This message is sent by the server, when it wants to know what properties need to be stored in the configuration, for this plugin and for this package. It also uses this information to create a view, for the user to provide information about the package.

The plugin will receive a request with following information.

Request name

package-configuration

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

The server will not provide request body.

Example response body

{
  "Field_1": {
    "display-name": "Package Spec",
    "display-order": "0",
    "default-value": "DEF",
    "secure": false,
    "part-of-identity": true,
    "required": true
  },
  "Field_2": {
    "display-name": "Field 2",
    "display-order": "1",
    "default-value": "ABC",
    "secure": true,
    "part-of-identity": true,
    "required": false
  }
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to return an object containing the configuration property along with package configuration object

Validate Repository Configuration

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  }
}

Request name

validate-repository-configuration

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This contains information about the repository-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” message.

Example response body

[
  {
    "key": "REPO_URL",
    "message": "Repository url not specified"
  },
  {
    "key": "RANDOM",
    "message": "Unsupported key(s) found : RANDOM. Allowed key(s) are : REPO_URL, USERNAME, PASSWORD"
  }
]

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to send a response, which contains a list of errors in the repository configuration, one message for every key in the request. It can also send an empty list, that is [], if the configuration is valid.

Validate Package Configuration

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  },
  "package-configuration": {
    "PACKAGE_SPEC": {
      "value": "sample-package-1.0"
    }
  }
}

Request name

validate-package-configuration

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This contains information about both the repository-level configuration and package-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” and “Package Configuration” messages.

Example response body

[
  {
    "key": "PACKAGE_SPEC",
    "message": "Package spec not specified"
  },
  {
    "key": "RANDOM",
    "message": "Unsupported key(s) found: RANDOM. Allowed key(s) are: PACKAGE_SPEC"
  }
]

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to send a response, which contains a list of errors in the package configuration, one message for every key in the request. It can also send an empty list, that is [], if the configuration is valid.

Check Repository Connection

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  }
}

Request name

check-repository-connection

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This contains information about the repository-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” message.

Example response body

{
  "status": "success",
  "messages": [
    "Successfully connected to repository url provided"
  ]
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to send a response, which contains a status (“success” or “failure”), and a list of error messages. This represents whether a connection was successfully made, to the repository specified in the request.

Check Package Connection

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  },
  "package-configuration": {
    "PACKAGE_SPEC": {
      "value": "sample-package-1.0"
    }
  }
}

Request name

check-package-connection

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This contains information about both the repository-level configuration and package-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” and “Package Configuration” messages.

Example response body

{
  "status": "success",
  "messages": [
    "Successfully found package abc.rpm"
  ]
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to send a response, which contains a status (“success” or “failure”), and a list of error messages. This represents whether a connection was successfully made, to find the package specified in the repository.

Latest Revision

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  },
  "package-configuration": {
    "PACKAGE_SPEC": {
      "value": "sample-package-1.0"
    }
  }
}

Request name

latest-revision

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This contains information about both the repository-level configuration and package-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” and “Package Configuration” messages.

Example response body

{
  "revision": "abc-10.2.1.rpm",
  "timestamp": "2011-07-14T19:43:37.100Z",
  "user": "some-user",
  "revisionComment": "comment",
  "trackbackUrl": "http://localhost:9999",
  "data": {
    "VERSION": "5.3.0",
    "LOCATION": "http://www.sample.org/location/of/package",
    "DATA-THREE": "data-three-value"
  }
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

The plugin is expected to send a response, which contains information about the latest revision it can find of the package specified by the information in the request. It can send an empty response ({}) to specify that it could not find a suitable package.

Almost all the fields expected in this response are explained in this part of the user documentation. The extra map, named “data” in the response, can be filled with custom keys and values, which will be made available to the agent, as environment variables, when a job contains this plugin as a material.

Latest Revision Since

The plugin will receive request with following information.

Example request body

{
  "repository-configuration": {
    "REPO_URL": {
      "value": "http://localhost.com"
    },
    "USERNAME": {
      "value": "user"
    },
    "PASSWORD": {
      "value": "password"
    }
  },
  "package-configuration": {
    "PACKAGE_SPEC": {
      "value": "sample-package-1.0"
    }
  },
  "previous-revision": {
    "revision": "abc-10.2.1.rpm",
    "timestamp": "2011-07-14T19:43:37.100Z",
    "data": {
      "VERSION": "5.3.0",
      "LOCATION": "http://www.sample.org/location/of/package",
      "DATA-THREE": "data-three-value"
    }
  }
}

Request name

latest-revision-since

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

This request is very similar to the request of the “Latest Revision” message. This contains information about both the repository-level configuration and package-level configuration provided by the user. The keys in the maps correspond to the keys provided by the plugin, as a part of the response to “Repository Configuration” and “Package Configuration” messages.

Along with that information, this request contains information about the previous revision of the package that GoCD knows about. Compare the “previous-revision” data of the example request shown below, with the response of the “Latest Revision” message to understand this.

Example response body

{
  "revision": "abc-10.2.2.rpm",
  "timestamp": "2011-07-14T19:45:37.100Z",
  "user": "some-user",
  "revisionComment": "comment 2",
  "trackbackUrl": "http://localhost:9999",
  "data": {
    "dataKeyOne": "data-value-one-1",
    "dataKeyTwo": "data-value-two-2"
  }
}

Response code

The plugin is expected to return status 200 if it can understand the request.

Response Body

Just as with the “Latest Revision” message, the plugin is expected to send a response, which contains information about the latest revision it can find of the package specified by the information in the request. The difference here, is that it needs to find a revision of the package which is greater than the one specified in the request. It can send an empty response ({}) to specify that it could not find a suitable package (for instance, if there has been no change, and the latest revision is still the one specified in the request).

Almost all the fields expected in this response are explained in this part of the user documentation. The extra map, named “data” in the response, can be filled with custom keys and values, which will be made available to the agent, as environment variables, when a job contains this plugin as a material.

Request/Response JSON Objects

The Repository Configuration Response Object

Here’s an example of the repository configuration response object:

{
  "REPO_URL": {
    "display-name": "Repository URL",
    "display-order": "0"
  },
  "USERNAME": {
    "part-of-identity": false,
    "required": false,
    "display-name": "User",
    "display-order": "1"
  },
  "PASSWORD": {
    "secure": true,
    "part-of-identity": false,
    "required": false,
    "display-name": "Password",
    "display-order": "2"
  }
}

Attribute Type Description
display-name String This option is used in the configuration UI, as a label of the input element.
display-order Integer This option is used in the configuration UI, to decide on the order in which the fields specified here need to be displayed.
default-value String A value to be used as the default if the user provides no value.
secure Boolean If the value should be stored in an encrypted form in the cruise-config.xml file.
part-of-identity Boolean Should the data for this field (provided by the user) be considered part of the identity of this material? Another way to think about this is: “If the user changes the value of this property, should GoCD consider this a new material?”. A good example for a property to be considered a part-of-identity is the URL (if the URL changes, it’s probably a different material). An example of a property which should not be considered part-of-identity is “password” (if the password or username changes, then it’s probably not a completely different material).
required Boolean Whether the field is required.

The Package Configuration Response Object

Here’s an example of the package configuration response object:

{
  "Field_1": {
    "display-name": "Package Spec",
    "display-order": "0",
    "default-value": "DEF",
    "secure": false,
    "part-of-identity": true,
    "required": true
  },
  "Field_2": {
    "display-name": "Field 2",
    "display-order": "1",
    "default-value": "ABC",
    "secure": true,
    "part-of-identity": true,
    "required": false
  }
}

Attribute Type Description
display-name String This option is used in the configuration UI, as a label of the input element.
display-order Integer This option is used in the configuration UI, to decide on the order in which the fields specified here need to be displayed.
default-value String A value to be used as the default if the user provides no value.
secure Boolean If the value should be stored in an encrypted form in the cruise-config.xml file.
part-of-identity Boolean Should the data for this field (provided by the user) be considered part of the identity of this material? Another way to think about this is: “If the user changes the value of this property, should GoCD consider this a new material?”. A good example for a property to be considered a part-of-identity is the URL (if the URL changes, it’s probably a different material). An example of a property which should not be considered part-of-identity is “password” (if the password or username changes, then it’s probably not a completely different material).
required Boolean Whether the field is required.