Pipeline API

Introduction

The Go API documented here is a work in progress. Future versions may change this API.

This API allows you to schedule new pipelines and unlock pipelines.

Scheduling pipelines

You can specify particular versions of the materials to use for the new pipeline. If you do not specify a particular revision for a material, Go will use the latest.

To choose which revision to use for a material it must have a materialName defined. By default the materialName of an upstream pipeline is the name of that pipeline. You can override this and specify a materialName, and then use this in the following APIs.

You can also parametrize your deployment script with environment variables at the time of triggering a pipeline. You can specify the value for any of the environment variables specified in the configuration file. This value will get carried all the way through to the relevant jobs. You can override the value of an environment variables specified at the environment, pipeline, stage or job level(in the configuration file) for that pipeline.

If a new value for an environment variable is not provided at the time of triggering the pipeline, then the values specified in the configuration file for this pipeline will be used.

Key

POST to URL http://[server]:8153/go/api/pipelines/[pipeline]/schedule with data as shown below.

Parameters
HTTP Verb	Data	Explanation
POST	no parameters	Triggers a new instance of the specified pipeline with the latest revision of all materials
POST	materials[svn_material]=3456	Triggers a new instance of the specified pipeline with revision 3456 of the svn material and the latest of all other materials
POST	materials[svn_material]=3456&materials[upstream_foo]=upstream_foo/2/dist/1	Triggers a new instance of the specified pipeline with revision 3456 of the svn material and instance 'upstream/2/dist/1' of the upstream pipeline
POST	materials[svn_material]=3456&materials[my-upstream-pipeline-name]=upstream_bar/2/dist/1	Triggers a new instance of the specified pipeline with revision 3456 of the svn material and instance 'upstream/2/dist/1' of the upstream pipeline. Here the upstream pipeline's materialName is set to 'my-upstream-pipeline-name'.

Examples

We use curl, a command line tool for transferring files with URL syntax, in the following examples. Of course, you can use any HTTP client library.
We assume that the URL of the Go server is http://goserver.com:8153/ .
We assume security has been switched on, and that there is a user named jez with the password badger .

The upstream pipeline (which is a material for 'foo') looks like:

                    <pipeline name="upstream_foo" labeltemplate="upstream_foo-1.0-${COUNT}">
                       <material>
                            <svn url="..."/>
                       </material>
                       <stage name="Dist">
                         <job name="dist">
                           <tasks>
                              <ant target="dist"/>
                           </tasks>
                         </job>
                       </stage>
                    </pipeline>
                    ....
                    <pipeline name="upstream_bar" labeltemplate="upstream_bar-1.2-${COUNT}">
                    ...

And the pipeline configuration looks like:

                    <pipeline name="foo" labeltemplete="foo-1.0-${COUNT}">
                       <environmentvariables>
                            <variable name="MACHINE_IP">10.22.12.2</variable>
                       </environmentvariables>
                       <material>
                            <svn url="http://thoughtworks.com:8080" materialName="svn_material"/>
                            <svn url="http://thoughtworks.com:8080" materialName="svn_material"/>
                            <pipeline pipelineName="upstream_foo" stageName="Dist"/>
                            <pipeline pipelineName="upstream_bar" stageName="Installers" materialName="my-upstream-pipeline-name"/>
                            <hg url="http://10.22.12.2:8000 materialName ="hg_material"/>
                       </material>
                       <stage name="DEV">
                         <environmentvariables>
                           <variable name="MACHINE_IP">10.22.2.12</variable>
                         </environmentvariables>
                         <job name="UnitTest">
                           <environmentvariables>
                              <variable name="TLB_TMP_DIR">C:\tlb_tmp_dir</variable>
                           </environmentvariables>
                           <tasks>
                              <ant target="ut"/>
                           </tasks>
                           <artifacts>
                              <artifact  src="coverage" dest="coveragereport.html"/>
                           </artifacts>
                         </job>
                       </stage>
                       <stage name="UATTest">
                         <job name="UAT">
                           <tasks>
                              <ant target="all-UAT"/>
                           </tasks>
                           <artifacts>
                              <artifact  src="report" dest="UATreport.html"/>
                              <artifact  src="target" dest="pkg/foo.war"/>
                           </artifacts>
                         </job>
                       </stage>
                    </pipeline>

If you want to trigger a new instance of the pipeline with the latest of all materials

curl -u jez:badger -d "" http://goserver.com:8153/go/api/pipelines/foo/schedule

If you want to trigger a new instance of the pipeline 'foo' with revision '3456' of your svn repository and instance 'upstream_foo/1/dist/2' of the upstream pipeline

curl -u jez:badger -d "materials[svn_material]=3456&materials[upstream_foo]=upstream_foo/1/dist/2" http://goserver.com:8153/go/api/pipelines/foo/schedule

If you want to trigger a new instance of the pipeline 'foo' with revision '3456' of your svn repository and instance 'upstream_bar/1/Installers/2' of the upstream pipeline

curl -u jez:badger -d "materials[svn_material]=3456&materials[my-upstream-pipeline-name]=upstream_bar/1/dist/2" http://goserver.com:8153/go/api/pipelines/foo/schedule

You can also use the following form, passing the materials as part of the URL

curl -u jez:badger -d "materials[svn_material]=3456&materials[upstream_foo]=upstream_foo/1/dist/2" http://goserver.com:8153/go/api/pipelines/foo/schedule

If you want to trigger a new instance of the pipeline 'foo' with revision '3456' of your svn repository and parametrize the environment variable MACHINE_IP with new value '10.21.2.2' for this specific run

curl -u jez:badger -d "materials[svn_material]=3456&variables[MACHINE_IP]=10.21.2.2" http://goserver.com:8153/go/api/pipelines/foo/schedule

If you want to trigger a new instance of the pipeline with the latest of all materials and parametrize the environment variable MACHINE_IP with new value '10.21.2.2' for this specific run

curl -u jez:badger -d "variables[MACHINE_IP]=10.21.2.2&variables[TLB_TMP_DIR]=C:\tlb_tmp_dir" http://goserver.com:8153/go/api/pipelines/foo/schedule

Releasing a pipeline lock

This API allows you to 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.

A pipeline lock can only be released when:

A locked pipeline has stopped because of a failed stage
A locked pipeline has stopped because of a canceled stage
A locked pipeline is waiting for a manual stage (i.e. a stage requiring manual approval)

Key

POST to URL http://[server]:8153/go/api/pipelines/[pipeline]/releaseLock with data as shown below.

Parameters
HTTP Verb	Data	Explanation
POST	no parameters	Releases a lock on the specified pipeline

Response Codes

HTTP response code	Explanation
200	pipeline lock released for [pipeline]
404	pipeline lock released for [pipeline]
406	no lock exists within the pipeline configuration for [pipeline]
406	lock exists within the pipeline configuration but no pipeline instance is currently in progress
406	locked pipeline instance is currently running (one of the stages is in progress)
401	user does not have operate permission on the pipeline

Examples

We use curl, a command line tool for transferring files with URL syntax, in the following examples. Of course, you can use any HTTP client library.
We assume that the URL of the Go server is http://goserver.com:8153/ .
We assume security has been switched on, and that there is a user named jez with the password badger .

The pipeline configuration looks like:

                    <pipeline name="foo" labeltemplete="foo-1.0-${COUNT}" isLocked="true">
                       <material>
                            <hg url="http://10.22.12.2:8000 materialName ="hg_material"/>
                       </material>
                       <stage name="DEV">
                         <job name="UnitTest">
                           <tasks>
                              <ant target="ut"/>
                           </tasks>
                         </job>
                       </stage>
                       <stage name="UATTest">
                         <job name="UAT">
                           <tasks>
                              <ant target="all-UAT"/>
                           </tasks>
                           <artifacts>
                              <artifact  src="target" dest="pkg/foo.war"/>
                           </artifacts>
                         </job>
                       </stage>
                    </pipeline>

Let's say the "DEV" stage failed in an instance of pipeline "foo" . Run this command to release the lock:

curl -u jez:badger -d "" http://goserver.com:8153/go/api/pipelines/foo/releaseLock

Scheduled Jobs

This api gives a list of all the current job instances which are scheduled but not yet assigned to any agent.

The XML output provides:

Pipeline, stage and their counters for this job instance.
Resources allotted to the job.
Environments the job's pipeline belongs to.
Environment Variables configured for the job.

Examples

We use curl, a command line tool for transferring files with URL syntax, in the following examples. Of course, you can use any HTTP client library.
We assume that the URL of the Go server is http://goserver.com:8153/ .
We assume security has been switched on, and that there is a user named jez with the password badger .

Run this command to get the list of scheduled jobs:

curl -u jez:badger -d ""  http://go-server.com:8153/go/api/jobs/scheduled.xml

Sample output is shown below:

        <scheduledJobs>
          <job name="fresh.install.go" id="186225">
            <link rel="self" href="http://go-server:8153/go/tab/build/detail/auto-deploy-testing-open-solaris/11/fresh-install/1/fresh.install.go"/>
            <buildLocator>
              auto-deploy-testing-open-solaris/11/fresh-install/1/fresh.install.go
            </buildLocator>
            <environment>AutoDeploy-OpenSolaris</environment>
            <resources>
              <resource>
                <autodeploy >
              </resource>
            </resources>
            <environmentVariables>
              <variable name="TWIST_SERVER_PATH">/etc/go</variable>
              <variable name="TWIST_SERVER_CONFIG_PATH">/etc/go</variable>
              <variable name="TWIST_AGENT_PATH">/var/lib/go-agent</variable>
            </environmentVariables>
          </job>
          <job name="publish" id="285717">
            <link rel="self" href="http://go-server:8153/go/tab/build/detail/go-ec2-plugin/26/dist/1/publish"/>
            <buildLocator>go-ec2-plugin/26/dist/1/publish</buildLocator>
            <environment>performance-ec2</environment>
            <resources>
              <resource>
                <deploy-agent>
              </resource>
            </resources>
          </job>
          <job name="upgrade" id="297092">
            <link rel="self" href="http://go-server:8153/go/tab/build/detail/upgrade_qa_server/15/upgrade/1/upgrade"/>
            <buildLocator>upgrade_qa_server/15/upgrade/1/upgrade</buildLocator>
            <environment>UAT</environment>
            <resources>
              <resource>
                <UAT-Server>
              </resource>
            </resources>
          </job>
        </scheduledJobs>

Help documentation

Pipeline API

Introduction

Scheduling pipelines

Key

Examples

Releasing a pipeline lock

Key

Response Codes

Examples

Scheduled Jobs

Examples