Jump to

• Request
• Response
• Examples

Start a build for a job

post

/v1/jobs/{jobName}/build

Returns a URI with the job identifier and build number from the started build, such as jobs/JOBID-345/builds/23

Request

Path Parameters

• jobName: string
  job name

Body ()

YAML parameters

Root Schema : schema

Type: string

Back to Top

Response

Supported Media Types

• text/plain

200 Response

jobs/JOBID-{jobId}/builds/{buildNo}

400 Response

Failed to schedule job {jobName} because {reason}

Back to Top

Examples

The following example shows how to start a build 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/jobs/A/build
Enter host password for user 'alex.admin':
jobs/JOBID-1/builds/40

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

A {jobIdentifier} can be used instead of {jobName}.

This command returns a text string that includes the job identifier and build number of the started build: jobs/JOBID-1/builds/40. Identifiers are returned in the format in which they would be used in a REST API URL. You can use a trivial regular expression to extract the job identifier and build number, if you want.

To pass non-empty parameters to a build, write the YAML into a file and use it (@myparams) in the cURL command:

curl -X POST -H 'Content-Type: text/plain' --data-binary @myparams -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_1/cibuild/v1/jobs/B/build
Enter host password for user 'alex.admin':
jobs/JOBID-2/builds/41

The myparams YAML input file would contain parameters, something 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

If the job can't be found, you'll see one of the following errors:

ERROR: Job {jobName} no longer exists
ERROR: Job identified by {jobIdentifier} no longer exists

If some other error prevented the job from running, you'll see this error:

ERROR: Failed to schedule job {jobName} because {reason}

Back to Top