Start a Build for a Job

You can start a build for a job (with or without parameters) using the REST API, and it'll return the build number. After that, you can use the build number returned by the parameterized job with the REST API and show the parameter definitions used in the job and the job's status:

1. In the Visual Builder Studio UI, go to the Project Home page and locate a project that has a build job.
2. Get the information you'll need to create the URL that you'll be using in the curl command.

   For Builds, the URL is composed this way:

   https://server/org-id/rest/org-id_project-id/cibuild/v1/jobs

   The first two parts of the URL (server/org-id) are quite easy to get. You can just copy them from the project's URL in your browser.

   The org-id_project-id part of the URL is something you can get by going to your project's Project Home page, clicking on the Repositories tab, and looking at the details of your Maven or Git repository URL. Look for the part before /maven/ or /scm/repository-name.git at the end. Some projects may also include a numeric value appended to the project name, something like org-id_project-name_27893.

   Note:

   If you're the project owner, you can select Project Administration in the navigator, click the Properties tile, then look in the Identifier field to find the org-id_project-id part of the URL.
3. Go to the Builds page and get the name of the job.
4. Run one of the following commands to start a non-parameterized or parameterized build:
   • Non-Parameterized
   • Parameterized

   You'll specify any input parameters with the -H 'Content-Type: text/plain' --data-binary '{}' portion of the command. In this example, we don't specify any parameters, so we use {} to denote an empty object:

   
   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/MyJob1NoParams/build
   Enter host password for user 'alex.admin':
   jobs/JOBID-1/builds/40

   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 used in a REST API URL.

   After you create a YAML file that contains parameters to be used in the build, you can use it (@myparams) in the cURL command to pass parameters to a build :

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

   This command returns a text string that includes the job identifier and build number of the started build: jobs/JOBID-2/builds/41. Identifiers are returned in the format used in a REST API URL. The job identifier and the job name can be used interchangeably. If you have one, you can always find the other, using the REST API. Use /v1/jobs/{jobIdentifier}/name to get the job name if you have the identifier or use /v1/jobs/{jobName}/id to get the job identifier if you have the name.

   The use of named passwords or named private keys is highly recommended for password parameters. See Use a Named Password/Private Key for more information. See Use Build Parameters for more information about build parameters that can be specified.

5. If you started a parameterized job, you can submit a GET request and return a list of the parameter definitions, in YAML format, that were used:

   
   curl -X GET -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_2/cibuild/v1/jobs/MyJob1Params/params
   Enter host password for user 'alex.admin':
   params:
   # Job MyJob1Params parameters:
   - password:
       secret="********"
   - choices="a"
   - GIT_REPO_URL="https://"
   - GIT_REPO_BRANCH="mybranch"
   - MERGE_REQ_ID="365273"
   - MY_PW="#{MY_PW}"

6. Finally, you can get the status of the job:

   
   curl -X GET -u alex.admin https://myinstance.oracle.com/myorg/rest/myorg_bobtest_1/cibuild/v1/jobs/MyJob1Params/builds/41/status
   Enter host password for user 'alex.admin':
   SUCCESSFUL

   The status indicates that the job was built successfully.