Assembla FAQ and Documentation

You must provide a Deploy Web Service on your build server to interface with Assembla’s Build tool. This page documents the web service actions and responses that will be needed to interface with the Build tool. The Deploy Web Service is a simple web application, that listens (by default) on port 44200, accepts HTTP requests, and posts responses back to the Build tool.

Actions list:

• configure
• deploy

Security

For all requests, there are three mandatory fields that should be checked each time:

• project name
• space tool ID
• secret key

The service should check for each request if project name is present, and stored values for space tool ID and secret key match the ones from request. There is one exception: if there is no default project configured yet, the space tool ID and secret key can be omitted.

If there is no project configured yet, the project configuration info from the first configuration request can be stored without checking space tool ID and secret key, and this project will be considered to be the default project. The first configuration request for the default project should be considered secure; subsequent configuration requests should pass entire security checking procedure.

configure action

Each time a user presses “Configure build server” in the Build tool, the Build tool will send thisa “configure” request to the Web Service. The action should respond with a textual value of a public ssh key for the deployment userid on the build server;server as the body of the HTTP Response.
The Build tool will set this key as the key of an Assembla bot user.user that you should use to checkout or clone your repository.

Additionally, the action should respond with an HTTP response code of “200 OK” if no project parameter is passed. This request represents a health check to assess if the action is available.

Parameters:

• project – project name
• space_tool_id – the id of the Build tool
• secret_key – the secret key of the tool
• config – the text with configuration info
  Note: All parameters are mandatory, with one exception: if default project is not defined yet, space_tool_id and secret_key can be omitted.

The text from config parameter is a bash script, that exports configuration variables. Here is a sample of config text that will be included in the configure action:

#!/bin/bash
export PROJECT_NAME=svnspace
export SPACE_TOOL_ID=cwIozk53r34gQnPaaWP00om
export SECRET_KEY=e934f76c7f23d49a1239ef38f91041b94b4aa3df
export POST_URL=http://www.assembla.com/tool_events
export SCM_URL=http://svn.assembla.com/svn/svnspace
export SCM=svn
export SCM_LOGIN=deploybot1330216441
export SCM_PASSWORD=dMPyQ25ci1234nPaaWP00om

deploy action

The most important action is deploy. This action will run build script/command sequence and post results back to Assembla. Note: please consider that builds can run for long periods of time, so we recommend running them in new threads (so HTTP request processing can complete quickly).

Additionally, the action should respond with an HTTP response code of “200 OK” if no project parameter is passed. This request represents a health check to assess if the action is available.

Mandatory parameters:

• project – project name
• space_tool_id – the id of the Build tool
• secret_key – the secret key of the tool

Optional parameters:

• on_commit – if value is “1”, this means the deploy request is initiated from commit event
• manual – if value is “1”, then the commit is initiated by a human user, by pressing the “Deploy” button

Posting build results

The deploy action should post results of the build to the POST_URL that was obtained during the configure action. These results will then be displayed in the Build tool’s “Build results” panel. The post should include a parameter list of these three HTTP variables:

• space_tool_id – provide the space_tool_id obtained during the configure action
• secret_key – provide the secret_key obtained during the configure action
• opts – provide a JSON-formatted structure containing variables and values for these additional options:
  • comment – an arbitrary short comment string
  • end_time – the build end time (formatted as a string of the form returned by UNIX ‘date +%c’, for example “Mon Feb 8 17:00:01 EST 2010”).
  • link – an optional URL linking to any external build results (for example, build statistics or test results). If omitted, Assembla will provide a link to a default build results page.
  • log – a detailed log of build results
  • start_time – the build start time (formatted as a string of the form returned by UNIX ‘date +%c’, for example “Mon Feb 8 17:00:01 EST 2010”).
  • status – (required) the status code of the build: 0 – success, any other integer – failed

An example of the JSON-formatted opts variable is:

{"start_time":"Mon Feb 08 15:23:27 -0500 2010","end_time":"Mon Feb 08 16:23:27 -0500 2010","status":0,"log":"This is a long log message","comment":"Short comment"}

Here is an example complete parameter list created using the above example opts variable (when SPACE_TOOL_ID is “abc123”, and when SECRET_KEY is “secretkey”):

space_tool_id=abc123&secret_key=secretkey&opts=%7b%22start_time%22%3a%22Mon%20Feb%2008%2015%3a23%3a27%20-0500%202010%22%2c%22status%22%3a0%2c%22log%22%3a%22This%20is%20a%20long%20log%20message%22%2c%22end_time%22%3a%22Mon%20Feb%2008%2016%3a23%3a27%20-0500%202010%22%2c%22comment%22%3a%22Short%20comment%22%7d

get_key action (deprecated)

This action will only be invoked if the configure action did not return a valid ssh key. This action should return the public ssh key of the build server deployment userid, and the Build tool will set this key as the key of an Assembla bot user.

Mandatory parameters:

• project – project name
• space_tool_id – the id of the Build tool
• secret_key – the secret key of the tool