Start a Pipeline

You can start a pipeline (with or without parameters) and return the pipeline instance identifier using the REST API. After that, you can use the REST API with the pipeline that has parameterized jobs, to show the parameter definitions that were used, retrieve the pipeline status, then show the pipeline instance log and see what happened during the run:

1. In the Project Home page, locate and open a project that has a pipeline.
   If you don't have such a project, you'll need to create one, add multiple jobs, and create a pipeline:

   • To create a project, follow the instructions in Create a Project in Using Visual Builder Studio.
   • To create a build job, follow the instructions in Create and Manage Jobs .
   • To create a pipeline, follow the instructions in Create a Pipeline.
2. Get the information that you'll need to create the URL used in the cURL command.

   For Pipelines, the URL is composed this way:

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

   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 Pipelines tab on the Builds page and find the name of the pipeline instance. You'll be using this information in the curl command.
4. Run one of the following commands to start a pipeline that runs non-parameterized or parameterized jobs:
   • Non-Parameterized
   • Parameterized

   Input parameters are specified using 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/pipelines/NoParamPipeline/start
   Enter host password for user 'alex.admin':
   pipelines/NoParamPipeline/instances/123

   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 you can use in subsequent requests to get the pipeline status and/or log.

   To pass parameters to a pipeline, create an input file that contains the YAML input parameters and reference it (@pipelineparams, in this case) 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

   This command returns a text string that includes the started pipeline's pipeline name and instance id (pipelines/NoParamPipeline/instances/124). You'll be using this information in subsequent requests to get the pipeline's parameter definitions, status, and log.

   If you're passing password parameters, using named passwords or named private keys is highly recommended. 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.

5. Get the parameter definitions used in the pipeline:

   Let's make sure that the correct parameters were used during the run.

   Use a curl command to submit a GET request on the REST resource that'll return the parameters that were defined for the jobs in the pipeline. You'll need to reference the pipeline name (ParamPipeline) and, if any pipeline job used parameters, those parameters will be returned in YAML format.

   
   curl -X GET -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_2/cibuild/v1/pipelines/ParamPipeline/params
   Enter host password for user 'alex.admin':
   params:
   # Pipeline ParamPipeline
   # Job A defines no parameters
   # Job B defines no parameters
   # Job C defines no parameters
   # Job D defines no parameters
   # Job E defines no parameters
   # Job Params parameters:
   - password:
       secret="********"
   - choices="a"
   - GIT_REPO_URL="https://"
   - GIT_REPO_BRANCH="mybranch"
   - MERGE_REQ_ID="365273"
   - MY_PW="#{MY_PW}"

6. Get the status of the ppipeline instance:

   Use a curl command to submit a GET request on the REST resource that'll return the pipeline instance status. You're trying to find out if the instance of the pipeline is still running or not. You'll need to reference the pipeline name (ParamPipeline) and pipeline instance (124) from the parameterized run in step 4.

   
   curl -X GET -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_2/cibuild/v1/pipelines/ParamPipeline/instances/124/status
   Enter host password for user 'alex.admin':
   NOT_RUNNING

   The pipeline isn't running. Hopefully it completed successfully. Let's look in the log and see what happened.

7. Get the log for the pipeline instance:

   Use a curl command to submit a GET request on the REST resource that'll retrieve a pipeline instance log showing job started/ended times, unusual conditions, etc. You'll need to reference the pipeline name (ParamPipeline) and pipeline instance (124) from the parameterized run in step 4 .

   
   curl -X GET -u alex.admin https://myinstance.mycompany.com/myorg/rest/myorg_mytest_2/cibuild/v1/pipelines/ParamPipeline/instances/124/log
   [2021-06-02 13:02:41] Started by user alex.admin
   [2021-06-02 13:02:46] Job [A] started
   [2021-06-02 13:03:10] Job [A] finished build
   [2021-06-02 13:03:11] Job [B] started
   [2021-06-02 13:03:12] Job [D] started
   [2021-06-02 13:04:04] Job [B] finished build
   [2021-06-02 13:04:04] Job [C] not run because upstream jobs [D]
   [2021-06-02 13:04:16] Job [D] finished build
   [2021-06-02 13:04:17] Job [C] started
   [2021-06-02 13:04:35] Job [C] finished build
   

   It looks like everything ran, once the blocking upstream job (D) completed.