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