Use Build Parameters

You can use build parameters for passing additional information to a build when it runs when that information isn't available at job configuration time.

You can configure a job to use a parameter and its value as an environment variable or through variable substitution in other parts of the job configuration. When a build runs, a Configure Parameters dialog box opens so you can enter or change the default values of the parameters:

1. Open the job’s detail page.
2. Click Configure.
3. Click the Parameters tab.
4. From the Add Parameter drop-down list, select the parameter type.

   You can add these types of build parameters:

   Use this parameter type ...	To:
   String	Accept a string value from the user when a build runs. The parameter field appears as a text box in the Configure Parameters dialog. Select the Required checkbox to ensure that no empty value is allowed when starting a build. If the parameter is set to required, a default value is mandatory and parameters in automatic builds always have non empty values. Using required parameters reduces build and pipeline failures caused by missing values for parameters.
   Password/Private Key	Accept a password or private key value from the user when a build runs. The parameter field appears as a password box in the Configure Parameters dialog. Select the Required checkbox to ensure that no empty value is allowed when starting a build. If the parameter is set to required, a default value is mandatory and parameters in automatic builds always have non empty values. Using required parameters reduces build and pipeline failures caused by missing values for parameters. It's important to note that the password/private key setting isn't a toggle. If you change the selection from password to private key (or private key to password), you'll need to re-enter the password/private key value.
   Boolean	Accept true or false as input from the user when a build runs. The parameter field appears as a check box in the Configure Parameters dialog.
   Choice	Accept a value from a list of values when a build runs. The parameter field appears as a drop-down list in the Configure Parameters dialog. The first value is the default selected value.
   Merge Request	Accepts string values for the Git repository URL, the Git repository branch name, and the merge request ID as input. The parameter fields appear as a text box in the Configure Parameters dialog. Use this parameter when you want to link an existing job with a merge request.

5. Enter values, such as name, default value, password/private key, and description.

   Note:

   Parameter names must contain letters, numbers or underscores only. They can't begin with a number and they aren't case-sensitive (the names "job", "JOB", and "Job" are all treated the same).

   You can't use hyphens in build parameter names. When the build system encounters a script or a command with a hyphenated build parameter name in a UNIX shell build step, it removes the portion of the name preceding the hyphen. If you try to use a hyphen in a build parameter name in a job, you won't be able to save the job configuration that includes it.

   In addition, you shouldn't use an underscore by itself or any of the system or other environmental variable names listed in Reserved Words that Shouldn't Be Used in Build Parameter Names as build parameter names. There could be unintended consequences if you do.

6. Click Save.

For example, if you want a job to change the default values for the Gradle version, the OCI username, and the OCI user password when a build runs, in a Build step, create the Choice, String, and Password/Private Key build parameters to accept the values. Notice that the value for the Password/Private Key parameter isn't displayed in the input field.

Description of the illustration devcs_buildparameters.png

Use the $BUILD_PARAMETER format when you're using build parameters. (The ${BUILD_PARAMETER} format can be used too.) For example, this screen shot shows the Gradle version, OCI username, and OCI password parameters used in the build step fields of a job. Notice that the password/private key parameter's variable name isn't displayed:

Description of the illustration devcs_buildparameters_config.png

When a build runs, the Configure Parameters dialog opens where you can enter or change the default values of parameters. All parameter values, except the Password/Private Key parameter's value, are displayed as string in the dialog box, and subsequently in the build log. This screenshot shows the dialog for a job configured to use a password parameter:

Description of the illustration devcs_buildparameters_run.png

This screenshot shows the dialog for a similar job configured to use a private key parameter instead of a password parameter:
Description of the illustration buildparameters_run_pkey.png Notice the difference instead of black dots) between the OCIPkey private key parameter's default value (asterisks) and that for the OCIPwd password parameter's default value shown in the previous screenshot.

If you selected the Use for Merge Request check box while creating the job, GIT_REPO_URL, GIT_REPO_BRANCH, and MERGE_REQ_ID Merge Request parameters are automatically added to accept the Git repository URL, the Git repository branch name, and the merge request ID as input from the merge request, respectively. The GIT_REPO_URL and GIT_REPO_BRANCH variables are automatically set in the Repository and Branch fields of the Git tab.

When a job in a pipeline runs, there is no way to enter or change the default values of the parameters. Job parameters in pipelines exhibit the following implicit behaviors:

• Upstream job parameters are passed to downstream jobs.

  For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A and parameter P2 is defined in Job B, then parameter P1 will be passed to Job B and parameters P1 and P2 will be passed to Job C.

• An upstream job with the same named parameter as a downstream job will overwrite the default value of the named parameter from the downstream job.

  For example, if parameters P1 and P2 are defined in Job A and parameters P2 and P3 are defined in Job B, then the value of parameter P2 from Job A will overwrite the default value of parameter P2 in Job B. If there was a Job C downstream from Job B, then the initial default value of P2 (from Job A) plus the values of P1 and P3 would be passed to Job C.

• When a build of the pipeline runs, the Configure Parameter dialog box displays all parameters of the jobs in the pipeline. Duplicate parameters are displayed once and its value is used by all jobs that use the parameter. The default value of a duplicate parameter comes from the first job in the pipeline where it is defined.

  For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A; parameters P2 and P3 are defined in Job 2; and parameters P1 and P4 are defined in Job C; then when the pipeline runs, it displays parameters P1, P2, P3, and P4 once in the Configure Parameter dialog box though parameter P1 is defined in two jobs. The default value of P1 would come from Job 1 and is passed to subsequent jobs of the pipeline.

  In the pipeline, if the Auto start when pipeline jobs are built externally is selected, then the Configure Parameter dialog box isn't displayed when a build of a pipeline's job runs. In the pipeline, the subsequent jobs of the job that trigger the build use the default values of their parameters. If a parameter is duplicate, then the job uses the default value of the first job where the parameter was defined.

  For example, in a pipeline that flows from Job A to Job B to Job C, if parameter P1 is defined in Job A; parameters P2 and P3 are defined in Job B; and parameters P1 and P4 are defined in Job C; then when a build of Job A runs, it passes the default value of P1 to Job B and Job C, and overwrites the default of P1 in Job C. If a build of Job B runs, then the builds use the default values of P2, P3, P1 (defined in Job C) and P4.

To learn about how to use build parameters in a Shell build step, see the GNU documentation on Shell Parameter Expansion at https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html.

Reserved Words that Shouldn't Be Used in Build Parameter Names

A system environment variable shouldn't be used as a parameter name. If you use one of the following system environment variable names, the build might run incorrectly or even fail unexpectedly:

• home
• hostname
• lang
• mail
• path
• pwd
• shell
• term
• user
• username

In addition, you should avoid using the following environment variables, listed alphabetically, that may be used elsewhere, to avoid interfering with the plugin or the process that introduced them:

• _ (underscore)
• ant_home
• build_dir, build_id, build_number
• cvs_rsh
• dcspassbuildinfofeaturecurrentorg, dcspassbuildinfofeaturecurrentproject
• g_broken_filenames, git_repo_branch, git_repo_url, gradle_home
• histcontrol, histsize, http_proxy, http_proxy_host, http_proxy_port, https_proxy, https_proxy_host, https_proxy_port
• isdcspassbuildinfofeatureenabled
• java_home, java_vendor, javacloud_home, javacloud_home_11_1_1_7_1, javacloud_home_11g, javacloud_home_soa, javacloud_home_soa_12_2_1, job_name
• lessopen, logname
• m2_home, merge_req_id, middleware_home, middleware_home_11_1_1_7_1, middleware_home_11g, middleware_home_soa, middleware_home_soa_12_2_1
• no_proxy, no_proxy_alt, node_path
• oracle_home, oracle_home_11_1_1_7_1, oracle_home_11g, oracle_home_soa, oracle_home_soa_12_2_1
• qtdir, qtinc, qtlib
• shlvl, ssh_askpass
• tool_path
• wls_home, wls_home_11_1_1_7_1, wls_home_11g, wls_home_soa, wls_home_soa_12_2_1, workspace