SCM Material Plugins

Extension Information


Availability	GoCD version 15.1.0 onwards
Extension Name	`scm`
Extension API Version	`1.0`

The SCM extension endpoint allows plugin authors to extend GoCD and integrate it with other SCMs.

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

A sample SCM material plugin - JGit |

Requests from the GoCD server

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

SCM Configuration
SCM View
Validate SCM Configuration
Check SCM Connection
Latest SCM Revision
Latest SCM Revisions Since
Checkout

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

The plugin will receive request with following information.

Request name

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

{
    "SCM_URL": {
        "display-name": "SCM 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 scm configuration object

SCM View

This message is sent by the server, to get a template to show to the user, to allow information about a SCM to be provided.

Request name

scm-view

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

{
   "displayValue": "JGit",
   "template": "<div class=\"form_item_block\"><label>Message:<span class=\"asterisk\">*</span></label><input type=\"text\" ng-model=\"message\" ng-required=\"true\"></div>"
}

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 view rendering information scm view response object

Validate SCM Configuration

Example request body

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

The plugin will receive request with following information.

Request name

validate-scm-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 SCM 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 “SCM Configuration” message.

Example response body

[
    {
        "key": "SCM_URL",
        "message": "SCM URL not specified"
    },
    {
        "key": "RANDOM",
        "message": "Unsupported key(s) found : RANDOM. Allowed key(s) are : SCM_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 SCM configuration, one message for every key in the request. It can also send an empty list, ie [], if the configuration is valid.

Check SCM Connection

Example request body

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

The plugin will receive request with following information.

Request name

check-scm-connection

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

Example response body

{
    "status": "success",
    "messages": [
        "Successfully connected to SCM 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 SCM specified in the request.

Latest Revision

Example request body

{
    "scm-configuration": {
        "SCM_URL": {
            "value": "http://localhost.com"
        },
        "USERNAME": {
            "value": "user"
        },
        "PASSWORD": {
            "value": "password"
        }
    },
    "flyweight-folder": "/var/lib/go-server/pipelines/flyweight-for-this-material"
}

The plugin will receive request with following information.

Request name

latest-revision

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

Example response body

{
    "revision": {
        "revision": "revision-1",
        "timestamp": "2011-07-14T19:43:37.100Z",
        "user": "some-user",
        "revisionComment": "comment",
        "data": {
            "dataKeyOne": "data-value-one",
            "dataKeyTwo": "data-value-two"
        },
        "modifiedFiles": [
            {
                "fileName": "file-1",
                "action": "added"
            }
        ]
    },
    "scm-data": {
        "dataKeyOne": "data-value-one",
        "dataKeyTwo": "data-value-two"
    }
}

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 SCM specified by the information in the request. It can send an empty response ({}) to specify that it could not find a revision.

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 key-value pairs, which will be made available to the agent, as environment variables, when a job contains this plugin as a material.

Latest Revisions Since

Example request body

{
    "scm-configuration": {
        "SCM_URL": {
            "value": "http://localhost.com"
        },
        "USERNAME": {
            "value": "user"
        },
        "PASSWORD": {
            "value": "password"
        }
    },
    "scm-data": {
        "dataKeyOne": "data-value-one",
        "dataKeyTwo": "data-value-two"
    },
    "flyweight-folder": "/var/lib/go-server/pipelines/flyweight-for-this-material",
    "previous-revision": {
        "revision": "revision-1",
        "timestamp": "2011-07-14T19:43:37.100Z",
        "data": {
          "dataKeyOne": "data-value-one",
          "dataKeyTwo": "data-value-two"
        }
    }
}

The plugin will receive request with following information.

Request name

latest-revisions-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 the SCM 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 “SCM Configuration” messages.

Along with that information, this request contains information about the previous revision of the SCM 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

{
    "revisions" : [
        {
            "revision": "revision-2",
            "timestamp": "2011-07-14T19:45:37.100Z",
            "user": "some-user",
            "revisionComment": "comment 2",
            "data": {
                "dataKeyOne": "data-value-one-1",
                "dataKeyTwo": "data-value-two-2"
            },
            "modifiedFiles": [
                {
                    "fileName": "file-2",
                    "action": "modified"
                }
            ]
        }
    ],
    "scm-data": {
        "dataKeyOne": "data-value-one",
        "dataKeyTwo": "data-value-three"
    }
}

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 SCM specified by the information in the request. The difference here, is that it needs to find a revisions of the SCM which is greater than the one specified in the request - previous-revision. It can send an empty response ({}) to specify that it could not find revisions (for instance, if there has been no change, and the latest revision is still the one specified in the request).

Checkout

Example request body

{
    "scm-configuration": {
        "SCM_URL": {
            "value": "http://localhost.com"
        },
        "USERNAME": {
            "value": "user"
        },
        "PASSWORD": {
            "value": "password"
        }
    },
    "destination-folder": "/var/lib/go-agent/pipelines/pipeline-name/destination",
    "revision": {
        "revision": "revision-1",
        "timestamp": "2011-07-14T19:43:37.100Z",
        "data": {
          "dataKeyOne": "data-value-one",
          "dataKeyTwo": "data-value-two"
        }
    }   
}

The plugin will receive request with following information.

Request name

checkout

Request parameters

The server will not provide any parameters.

Request headers

The server will not provide any headers.

Request body

Example response body

{
    "status": "success",
    "messages": [
        "Successfully checked out to SCM revision 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 checkout was successfully made, to the SCM specified in the request.

Request/Response JSON Objects

The SCM Configuration Response Object

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

{
  "SCM_URL": {
    "display-name": "SCM 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
`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.
`required`	Boolean	Whether the field is required.

The SCM View Response Object

Here’s an example of the scm view response object:

{
  "displayValue": "SCM name",
  "template": "<div class=\"form_item_block\">...</div>"
}

Attribute	Type	Description
`displayValue`	String	The name of the scm that should be rendered in the view.
`template`	String	A string containing an HTML AngularJS based view.

GoCD uses Angular JS as its template engine for the plugin UI. This allows plugin authors to use a limited set of AngularJS features to specify how the UI of their plugins looks.

Getting started with AngularJS based templates

Given a configuration:

<configuration>
  <property>
    <key>username</key>
    <value>alice</username>
  </property>
</configuration>

This gets converted into the following JSON representation in the browser:

{
  "username": "alice"
}

The AngularJS template is expected to bind to the JSON object shown above:

<div class="form_item_block">
  <label>Username:<span class='asterix'>*</span></label>
  <input ng-model="username" />
</div>

When an Angular template is used in a Go plugin, to define the configuration UI, the configuration key which is stored in the configuration XML is used everywhere and is expected to be consistent. Since Angular works off of JSON, GoCD will make sure that the key in the JSON provided to the Angular template is the same as the key in the configuration XML.

Suppose the key of the configuration property stored in the XML is “username”, with value, “alice”, then Go will make sure that the value is available to the template as “username” when used in an Angular-specific HTML attribute like “ng-model”.

Plugin Angular Architecture

So, the name “foobar” needs to be the same across the configuration XML, the Angular template as well as in any code that the plugin has.

Showing validation errors in the UI

We use some simple string replacement
to substitute GOINPUTNAME with a unique identifier
for your plugin in order to render
any server side errors

<div class="form_item_block">
  <label>Username:<span class='asterix'>*</span></label>
  <input ng-model="username" />
  <span class="form_error" ng-show="GOINPUTNAME[username].$error.server">
    {{ GOINPUTNAME[username].$error.server}}
  </span>
</div>

In case of validation errors returned by go.plugin-settings.validate-configuration, the error messages needs to be populated on the UI, use the snippet here to show the validation errors.