Jump to

• Request
• Response
• Examples

Start a pipeline

post

/v1/pipelines/{pipelineName}/start

Returns a URI with the pipeline name and instance, such as pipelines/Example/instances/344

Request

Supported Media Types

• text/plain

Path Parameters

• pipelineName: string
  pipeline name

Body ()

YAML parameters

Root Schema : schema

Type: string

Back to Top

Response

Supported Media Types

• text/plain

200 Response

pipelines/{pipelineName}/instances/{instanceId}

400 Response

ERROR: Errors in parameters YAML

401 Response

ERROR: Not authorized

403 Response

ERROR: Error processing {request}

409 Response

ERROR: Pipeline {pipelineName} cannot be started

Back to Top

Examples

The following example shows how to start a pipeline by submitting a POST request on the REST resource using curl.

curl -X POST -H 'Content-Type: text/plain' --data-binary "{}" -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_1/cibuild/v1/pipelines/NoParamPipeline/start
Enter host password for user 'alex.admin':
pipelines/NoParamPipeline/instances/123

The -H 'Content-Type: text/plain' --data-binary '{}' portion of the command specifies the input parameters. In this example, we don't specify any parameters. {} denotes an empty object, no parameters.

This command returns a text string that includes the pipeline name and instance id of the started pipeline (pipelines/NoParamPipeline/instances/123). Results are returned in a format that can be used in subsequent requests to get the pipeline status and/or log.

To pass parameters to a pipeline, create a file (@pipelineparams, in this case) that contains the YAML input parameters and reference it in the cURL command:

curl -X POST -H 'Content-Type: text/plain' --data-binary @pipelineparams -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_2/cibuild/v1/pipelines/ParamPipeline/start
Enter host password for user 'alex.admin':
pipelines/ParamPipeline/instances/124

The YAML input file could contain parameters, like these:

params:
  - name=true      # boolean parameter (true or false)
  - name=#{NP}     # password parameter (NP is the name of a named password)
  - name=value     # string parameter (any other value)
  - password:      # password parameter (plaintext value)
      name=value

Using a variable called a named password/private key, such as the one in the following example, is highly recommended for password parameters:

MY_PW=#{SECRET_PASSWORD}

See Use a Named Password/Private Key for more information. See Use Build Parameters for more information about input parameters that can be specified in the file that is referenced.

Errors

You'll see this error if the pipeline can't be found:

ERROR: No such pipeline {pipelineName}

You'll see this error if the pipeline is already running or can't be run for some other reason:

ERROR: Pipeline <pipelineName> cannot be started

Back to Top