docs/jjb/lf-python-jobs.rst

   1 ###########
   2 Python Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 .. include:: ../job-groups.rst
   9
  10 Below is a list of Python job groups:
  11
  12 .. literalinclude:: ../../jjb/lf-python-job-groups.yaml
  13    :language: yaml
  14
  15
  16 Macros
  17 ======
  18
  19 lf-infra-clm-python
  20 -------------------
  21
  22 Runs CLM scanning against a Python project.
  23
  24 :Required Parameters:
  25
  26     :clm-project-name: Project name in Nexus IQ to send results to.
  27
  28 lf-infra-pypi-tag-release
  29 -------------------------
  30
  31 Checks the format of the release version string and checks the git
  32 repository for that tag. In a merge job, if the tag does not exist,
  33 adds the tag to the repository, signs the tag, and pushes the tag
  34 to the git server. Signing requires sigul, which is only available
  35 on a CentOS build node.
  36
  37 lf-infra-pypi-upload
  38 --------------------
  39
  40 Uploads distribution files from subdirectory "dist" to a PyPI repository
  41 using a Python virtual enviroment to install required packages. The
  42 Jenkins server must have a configuration file ".pypirc".
  43
  44 :Required Parameters:
  45
  46     :pypi-repo: PyPI repository key in .pypirc configuration file;
  47         e.g., "pypi-test" or "pypi".
  48
  49 lf-infra-tox-install
  50 --------------------
  51
  52 Installs Tox into a virtualenv.
  53
  54 :Required Parameters:
  55
  56     :python-version: Version of Python to invoke the pip install of the tox-pyenv
  57         package that creates a virtual environment, either "python2" or "python3".
  58
  59 lf-infra-tox-run
  60 ----------------
  61
  62 Creates a Tox virtual environment and invokes tox.
  63
  64 :Required Parameters:
  65
  66     :parallel: Boolean. If true use detox (distributed tox);
  67         else use regular tox.
  68
  69
  70 Job Templates
  71 =============
  72
  73 Python XC CLM
  74 -------------
  75
  76 CLM scans for Python based repos. This job will call the Nexus IQ CLI
  77 directly to run the scans.
  78
  79 A new credential named "nexus-iq-xc-clm" needs to exist in the Jenkins
  80 credentials.  The credential should contain the username and password
  81 to access Nexus IQ Server.
  82
  83 :Template Names:
  84
  85     - {project-name}-python-clm-{stream}
  86     - gerrit-python-xc-clm
  87     - github-python-xc-clm
  88
  89 :Comment Trigger: run-clm
  90
  91 :Required parameters:
  92
  93     :build-node: The node to run build on.
  94     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  95         get configured in defaults.yaml)
  96
  97 :Optional parameters:
  98
  99     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 100     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
 101         (default: 1.44.0-01)
 102     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
 103         share a Nexus IQ system to avoid project name collision. We recommend
 104         inserting a trailing - dash if using this parameter.
 105         For example 'odl-'. (default: '')
 106     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 107     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 108     :java-version: Version of Java to use for the build. (default: openjdk8)
 109     :pre-build-script: Shell script to execute before the CLM builder.
 110         For example, install prerequisites or move files to the repo root.
 111         (default: a string with a shell comment)
 112     :stream: Keyword used to represent a release code-name.
 113         Often the same as the branch. (default: master)
 114     :submodule-recursive: Whether to checkout submodules recursively.
 115         (default: true)
 116     :submodule-timeout: Timeout (in minutes) for checkout operation.
 117         (default: 10)
 118     :submodule-disable: Disable submodule checkout operation.
 119         (default: false)
 120     :gerrit_clm_triggers: Override Gerrit Triggers.
 121     :gerrit_trigger_file_paths: Override file paths used to filter which file
 122         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 123         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 124
 125
 126 Python Sonar with Tox
 127 ---------------------
 128
 129 Sonar scans for Python based repos. This job invokes tox to run tests
 130 and gather coverage statistics from the test results, then invokes
 131 Maven to publish the results to a Sonar server.
 132
 133 To get the Sonar coverage results, file tox.ini must exist and contain
 134 coverage commands to run.
 135
 136 The coverage commands define the code that gets executed by the test
 137 suites.  Checking coverage does not guarantee that the tests execute
 138 properly, but it identifies code that is not executed by any test.
 139
 140 This job reuses the Sonar builder used in Java/Maven projects which
 141 runs maven twice. The first invocation does nothing for Python
 142 projects, so the job uses the goal 'validate' by default. The second
 143 invocation publishes results using the goal 'sonar:sonar' by default.
 144
 145 For example:
 146
 147 .. code-block:: bash
 148
 149     [testenv:py27]
 150     commands =
 151             coverage run --module pytest --junitxml xunit-results.xml
 152             coverage xml --omit=".tox/py27/*","tests/*"
 153             coverage report --omit=".tox/py27/*","tests/*"
 154
 155 For more details refer to coverage and sonar documentation:
 156
 157 https://coverage.readthedocs.io/
 158
 159 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 160
 161 :Template Names:
 162
 163     - {project-name}-tox-sonar
 164     - gerrit-tox-sonar
 165     - github-tox-sonar
 166
 167 :Comment Trigger: run-sonar
 168
 169 :Required parameters:
 170
 171     :build-node: The node to run build on.
 172     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 173         get configured in defaults.yaml)
 174     :mvn-settings: The name of the settings file with credentials for the project.
 175
 176 :Optional parameters:
 177
 178     :branch: Git branch, should be master (default: master)
 179     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 180     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 181     :cron: Cron schedule when to trigger the job. This parameter also
 182         supports multiline input via YAML pipe | character in cases where
 183         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 184         to run once a day)
 185     :disable-job: Whether to disable the job (default: false)
 186     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 187     :github-url: URL for Github. (default: https://github.com)
 188     :java-version: Version of Java to use for the build. (default: openjdk8)
 189     :mvn-global-settings: The name of the Maven global settings to use for
 190     :mvn-goals: The Maven goal to run first. (default: validate)
 191     :mvn-version: Version of maven to use. (default: mvn35)
 192     :parallel: Boolean indicator for tox to run tests in parallel or series.
 193        (default: false, in series)
 194     :pre-build-script: Shell script to execute before the Sonar builder.
 195         For example, install prerequisites or move files to the repo root.
 196         (default: a string with a shell comment)
 197     :python-version: Python version to invoke pip install of tox-pyenv
 198         (default: python2)
 199     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 200     :stream: Keyword used to represent a release code-name.
 201         Often the same as the branch. (default: master)
 202     :submodule-recursive: Whether to checkout submodules recursively.
 203         (default: true)
 204     :submodule-timeout: Timeout (in minutes) for checkout operation.
 205         (default: 10)
 206     :submodule-disable: Disable submodule checkout operation.
 207         (default: false)
 208     :gerrit_sonar_triggers: Override Gerrit Triggers.
 209     :gerrit_trigger_file_paths: Override file paths used to filter which file
 210         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 211         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 212
 213
 214 Tox Verify
 215 ----------
 216
 217 Tox runner to verify a project on creation of a patch set.  This job
 218 is pyenv aware so if the image contains an installation of pyenv at
 219 /opt/pyenv it will pick it up and run Python tests with the
 220 appropriate Python versions. This job will set the following pyenv
 221 variables before running.
 222
 223 .. code:: bash
 224
 225    export PYENV_ROOT="/opt/pyenv"
 226    export PATH="$PYENV_ROOT/bin:$PATH"
 227
 228 :Template Names:
 229
 230     - {project-name}-tox-verify-{stream}
 231     - gerrit-tox-verify
 232     - github-tox-verify
 233
 234 :Comment Trigger: recheck|reverify
 235
 236 :Required Parameters:
 237
 238     :build-node: The node to run build on.
 239     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 240         in defaults.yaml)
 241
 242 :Optional Parameters:
 243
 244     :branch: The branch to build against. (default: master)
 245     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 246     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 247     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 248     :pre-build-script: Shell script to execute before the Tox builder.
 249         For example, install prerequisites or move files to the repo root.
 250         (default: a string with a shell comment)
 251     :parallel: Boolean indicator for tox to run tests in parallel or series.
 252        (default: false, in series)
 253     :python-version: Python version to invoke pip install of tox-pyenv
 254         (default: python2)
 255     :stream: Keyword representing a release code-name.
 256         Often the same as the branch. (default: master)
 257     :submodule-recursive: Whether to checkout submodules recursively.
 258         (default: true)
 259     :submodule-timeout: Timeout (in minutes) for checkout operation.
 260         (default: 10)
 261     :submodule-disable: Disable submodule checkout operation.
 262         (default: false)
 263     :tox-dir: Directory containing the project's tox.ini relative to
 264         the workspace. The default uses tox.ini at the project root.
 265         (default: '.')
 266     :tox-envs: Tox environments to run. If blank run everything described
 267         in tox.ini. (default: '')
 268     :gerrit_trigger_file_paths: Override file paths used to filter which file
 269         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 270         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 271
 272
 273 Tox Merge
 274 ---------
 275
 276 Tox runner to verify a project after merge of a patch set.  This job
 277 is pyenv aware so if the image contains an installation of pyenv at
 278 /opt/pyenv it will pick it up and run Python tests with the
 279 appropriate Python versions. This job will set the following pyenv
 280 variables before running.
 281
 282 .. code:: bash
 283
 284    export PYENV_ROOT="/opt/pyenv"
 285    export PATH="$PYENV_ROOT/bin:$PATH"
 286
 287 :Template Names:
 288
 289     - {project-name}-tox-merge-{stream}
 290     - gerrit-tox-merge
 291     - github-tox-merge
 292
 293 :Comment Trigger: remerge
 294
 295 :Required Parameters:
 296
 297     :build-node: The node to run build on.
 298     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 299         in defaults.yaml)
 300
 301 :Optional Parameters:
 302
 303     :branch: The branch to build against. (default: master)
 304     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 305     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 306     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 307     :pre-build-script: Shell script to execute before the CLM builder.
 308         For example, install prerequisites or move files to the repo root.
 309         (default: a string with only a comment)
 310     :python-version: Python version to invoke pip install of tox-pyenv
 311         (default: python2)
 312     :stream: Keyword representing a release code-name.
 313         Often the same as the branch. (default: master)
 314     :submodule-recursive: Whether to checkout submodules recursively.
 315         (default: true)
 316     :submodule-timeout: Timeout (in minutes) for checkout operation.
 317         (default: 10)
 318     :submodule-disable: Disable submodule checkout operation.
 319         (default: false)
 320     :tox-dir: Directory containing the project's tox.ini relative to
 321         the workspace. The default uses tox.ini at the project root.
 322         (default: '.')
 323     :tox-envs: Tox environments to run. If blank run everything described
 324         in tox.ini. (default: '')
 325     :gerrit_trigger_file_paths: Override file paths used to filter which file
 326         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 327         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 328
 329
 330 PyPI Verify
 331 -----------
 332
 333 Verifies a Python library project on creation of a patch set. Runs tox
 334 then builds a source distribution and (optionally) a binary
 335 distribution. The project repository must have a setup.py file with
 336 configuration for packaging the component.
 337
 338 The tox runner is pyenv aware so if the image contains an installation
 339 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 340 the appropriate Python versions. The tox runner sets the following
 341 pyenv variables before running.
 342
 343 .. code:: bash
 344
 345    export PYENV_ROOT="/opt/pyenv"
 346    export PATH="$PYENV_ROOT/bin:$PATH"
 347
 348 :Template Names:
 349
 350     - {project-name}-pypi-verify-{stream}
 351     - gerrit-pypi-verify
 352     - github-pypi-verify
 353
 354 :Comment Trigger: recheck
 355
 356 :Required Parameters:
 357
 358     :build-node: The node to run the build on.
 359     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 360         in defaults.yaml)
 361
 362 :Optional Parameters:
 363
 364     :branch: The branch to build against. (default: master)
 365     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 366     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 367     :disable-job: Whether to disable the job (default: false)
 368     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 369     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 370     :parallel: Boolean indicator for tox to run tests in parallel or series.
 371        (default: false, in series)
 372     :pre-build-script: Shell script to execute before the tox builder. For
 373         example, install system prerequisites. (default: a shell comment)
 374     :python-version: Python version to invoke pip install of tox-pyenv
 375         (default: python3)
 376     :stream: Keyword representing a release code-name.
 377         Often the same as the branch. (default: master)
 378     :submodule-recursive: Whether to checkout submodules recursively.
 379         (default: true)
 380     :submodule-timeout: Timeout (in minutes) for checkout operation.
 381         (default: 10)
 382     :submodule-disable: Disable submodule checkout operation.
 383         (default: false)
 384     :tox-dir: Directory containing the project's tox.ini relative to
 385         the workspace. The default uses tox.ini at the project root.
 386         (default: '.')
 387     :tox-envs: Tox environments to run. If blank run everything described
 388         in tox.ini. (default: '')
 389     :gerrit_trigger_file_paths: Override file paths used to filter which file
 390         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 391         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 392
 393
 394 PyPI Merge
 395 ----------
 396
 397 Creates and uploads distribution files on merge of a patch set. Runs
 398 tox, builds a source distribution and (optionally) a binary
 399 distribution, and uploads the distribution(s) to a PyPI repository.
 400 This job should be configured to use a test PyPI repository like
 401 testpypi.python.org, not a public release area like the global PyPI
 402 repository. Like the verify job, this requires a setup.py file for
 403 packaging the component.
 404
 405 The tox runner is pyenv aware so if the image contains an installation
 406 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 407 the appropriate Python versions. The tox runner sets the following
 408 pyenv variables before running.
 409
 410 .. code:: bash
 411
 412    export PYENV_ROOT="/opt/pyenv"
 413    export PATH="$PYENV_ROOT/bin:$PATH"
 414
 415
 416 Requires a .pypirc configuration file in the Jenkins builder home directory,
 417 an example appears next that uses API tokens. No repository is needed in the
 418 PyPI section.
 419
 420 .. code-block:: bash
 421
 422     [distutils] # this tells distutils what package indexes you can push to
 423     index-servers = pypi-test pypi
 424
 425     [pypi-test]
 426     repository: https://test.pypi.org/legacy/
 427     username: __token__
 428     password: pypi-test-api-token-goes-here
 429
 430     [pypi]
 431     username: __token__
 432     password: pypi-api-token-goes-here
 433
 434
 435 :Template Names:
 436
 437     - {project-name}-pypi-merge-{stream}
 438     - gerrit-pypi-merge
 439     - github-pypi-merge
 440
 441 :Comment Trigger: pypi-remerge
 442
 443 :Required Parameters:
 444
 445     :build-node: The node to run the build on.
 446     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 447         in defaults.yaml)
 448
 449 :Optional Parameters:
 450
 451     :branch: The branch to build against. (default: master)
 452     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 453     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 454     :cron: Cron schedule when to trigger the job. Supports daily builds.
 455         This parameter also supports multiline input via YAML pipe | character in
 456         cases where one may want to provide more than 1 cron timer. (default: empty)
 457     :disable-job: Whether to disable the job (default: false)
 458     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 459     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 460     :parallel: Boolean indicator for tox to run tests in parallel or series.
 461        (default: false, in series)
 462     :pre-build-script: Shell script to execute before the tox builder. For
 463         example, install system prerequisites. (default: a shell comment)
 464     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
 465         Merge jobs should use a server like testpypi.python.org. (default: pypi-test)
 466     :python-version: Python version to invoke pip install of tox-pyenv
 467         (default: python3)
 468     :stream: Keyword representing a release code-name.
 469         Often the same as the branch. (default: master)
 470     :submodule-recursive: Whether to checkout submodules recursively.
 471         (default: true)
 472     :submodule-timeout: Timeout (in minutes) for checkout operation.
 473         (default: 10)
 474     :submodule-disable: Disable submodule checkout operation.
 475         (default: false)
 476     :tox-dir: Directory containing the project's tox.ini relative to
 477         the workspace. The default uses tox.ini at the project root.
 478         (default: '.')
 479     :tox-envs: Tox environments to run. If blank run everything described
 480         in tox.ini. (default: '')
 481     :gerrit_trigger_file_paths: Override file paths used to filter which file
 482         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 483         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 484
 485
 486 PyPI Release Verify
 487 -------------------
 488
 489 Verifies a Python library project on creation of a patch set with a
 490 release yaml file. Runs tox, builds source and (optionally) binary
 491 distributions, checks the format of the version string, checks that
 492 the distribution file names contain the release version string, and
 493 checks if the tag exists in the code repository for the release
 494 version.
 495
 496 To initiate the release process, create a releases/ or .releases/
 497 directory at the root of the project repository, add one release yaml
 498 file to it, and submit a change set with that release yaml file. A
 499 schema and and an example for the release yaml file appear below. The
 500 version in the release yaml file must be a valid Semantic Versioning
 501 (SemVer) string, matching either the pattern "v#.#.#" or "#.#.#" where
 502 "#" is one or more digits.
 503
 504 This job is similar to the PyPI verify job, but is only triggered by a
 505 patch set with a release yaml file.
 506
 507 The build node for PyPI release verify jobs must be CentOS, which
 508 supports the sigul client for accessing a signing server.
 509
 510 .. note::
 511
 512    The release file regex is: (releases\/.*\.yaml|\.releases\/.*\.yaml).
 513    In words, the directory name can be ".releases" or "releases"; the file
 514    name can be anything with suffix ".yaml".
 515
 516 The JSON schema for a pypi release file appears below.
 517
 518 .. code-block:: none
 519
 520     ---
 521     $schema: "http://json-schema.org/schema#"
 522     $id: "https://github.com/lfit/releng-global-jjb/blob/master/release-pypi-schema.yaml"
 523
 524     required:
 525       - "distribution_type"
 526       - "project"
 527       - "version"
 528
 529     properties:
 530       distribution_type:
 531         type: "string"
 532       project:
 533         type: "string"
 534       version:
 535         type: "string"
 536
 537
 538 An example of a pypi release file appears below.
 539
 540 .. code-block:: none
 541
 542     $ cat releases/1.0.0-pypi.yaml
 543     ---
 544     distribution_type: pypi
 545     version: 1.0.0
 546     project: 'example-project'
 547
 548
 549 :Template Names:
 550
 551     - {project-name}-pypi-release-verify-{stream}
 552     - gerrit-pypi-release-verify
 553     - github-pypi-release-verify
 554
 555 :Required Parameters:
 556
 557     :build-node: The node to run build on, which must be Centos.
 558     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 559         in defaults.yaml)
 560
 561 :Optional Parameters:
 562
 563     :branch: The branch to build against. (default: master)
 564     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 565     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 566     :disable-job: Whether to disable the job (default: false)
 567     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 568     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 569     :parallel: Boolean indicator for tox to run tests in parallel or series.
 570        (default: false, in series)
 571     :pre-build-script: Shell script to execute before the tox builder.
 572         For example, install prerequisites or move files to the repo root.
 573         (default: a string with a shell comment)
 574     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
 575         Release jobs should use a server like pypy.org. (default: pypi)
 576     :python-version: Python version to invoke pip install of tox-pyenv
 577         (default: python3)
 578     :stream: Keyword representing a release code-name.
 579         Often the same as the branch. (default: master)
 580     :submodule-recursive: Whether to checkout submodules recursively.
 581         (default: true)
 582     :submodule-timeout: Timeout (in minutes) for checkout operation.
 583         (default: 10)
 584     :submodule-disable: Disable submodule checkout operation.
 585         (default: false)
 586     :tox-dir: Directory containing the project's tox.ini relative to
 587         the workspace. The default uses tox.ini at the project root.
 588         (default: '.')
 589     :tox-envs: Tox environments to run. If blank run everything described
 590         in tox.ini. (default: '')
 591     :use-release-file: Whether to use the release file. (default: true)
 592
 593 PyPI Release Merge
 594 ------------------
 595
 596 Publishes a Python library on merge of a patch set with a release yaml
 597 file. Runs tox, builds source and (optionally) binary distributions,
 598 checks the format of the version string, checks that the distribution
 599 file names contain the release version string, checks if the tag
 600 exists in the code repository for the release version, then if the tag
 601 does not exist, tags the code repository with the release version,
 602 signs the tag and pushes the tag to the git server. Finally this
 603 uploads the distributions to a PyPI repository.
 604
 605 This job is similar to the PyPI merge job, but is only triggered by
 606 merge of a release yaml file, also this checks the version and tag
 607 before uploading to a public repository such as PyPI.
 608
 609 See the PyPI Release Verify job above for documentation of the release
 610 yaml file format.
 611
 612 The build node for PyPI release merge jobs must be CentOS, which
 613 supports the sigul client for accessing a signing server.
 614
 615 A Jenkins user can also trigger this release job via the "Build with
 616 parameters" action, removing the need to merge a release yaml file.
 617 The user must enter parameters in the same way as a release yaml file,
 618 except for the special USE_RELEASE_FILE and DRY_RUN check boxes. The
 619 user must uncheck the USE_RELEASE_FILE check box if the job should run
 620 with a release file, while passing the required information as build
 621 parameters. Similarly, the user must uncheck the DRY_RUN check box to
 622 test the job while skipping upload of files to a repository.
 623
 624 The special parameters are as follows::
 625
 626     VERSION = 1.0.0
 627     USE_RELEASE_FILE = false
 628     DRY_RUN = false
 629
 630 :Template Names:
 631
 632     - {project-name}-pypi-release-merge-{stream}
 633     - gerrit-pypi-release-merge
 634     - github-pypi-release-merge
 635
 636 :Required Parameters:
 637
 638     :build-node: The node to run build on, which must be Centos.
 639     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 640         in defaults.yaml)
 641
 642 :Optional Parameters:
 643
 644     :branch: The branch to build against. (default: master)
 645     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 646     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 647     :disable-job: Whether to disable the job (default: false)
 648     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 649     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 650     :parallel: Boolean indicator for tox to run tests in parallel or series.
 651        (default: false, in series)
 652     :pre-build-script: Shell script to execute before the tox builder.
 653         For example, install prerequisites or move files to the repo root.
 654         (default: a string with a shell comment)
 655     :pypi-repo: Key for PyPI repository parameters in the .pypirc file.
 656         Release jobs should use a server like pypy.org. (default: pypi)
 657     :python-version: Python version to invoke pip install of tox-pyenv
 658         (default: python3)
 659     :stream: Keyword representing a release code-name.
 660         Often the same as the branch. (default: master)
 661     :submodule-recursive: Whether to checkout submodules recursively.
 662         (default: true)
 663     :submodule-timeout: Timeout (in minutes) for checkout operation.
 664         (default: 10)
 665     :submodule-disable: Disable submodule checkout operation.
 666         (default: false)
 667     :tox-dir: Directory containing the project's tox.ini relative to
 668         the workspace. The default uses tox.ini at the project root.
 669         (default: '.')
 670     :tox-envs: Tox environments to run. If blank run everything described
 671         in tox.ini. (default: '')
 672     :use-release-file: Whether to use the release file. (default: true)