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-nexus-iq-python-cli
  20 ----------------------------
  21
  22 Runs Nexus IQ command-line interface CLM scan on Python package requirements.
  23
  24 :Required Parameters:
  25
  26     :nexus-iq-project-name: Project name in Nexus IQ to send results to.
  27     :requirements-file: File name with output of pip freeze.
  28
  29 lf-infra-tox-install
  30 --------------------
  31
  32 Installs Tox into a virtualenv.
  33
  34 :Required Parameters:
  35
  36     :python-version: Version of Python to invoke the pip install of the tox-pyenv
  37         package that creates a virtual environment, either "python2" or "python3".
  38
  39 lf-infra-tox-run
  40 ----------------
  41
  42 Creates a Tox virtual environment and invokes tox.
  43
  44 :Required Parameters:
  45
  46     :parallel: If different from false, try pass this parameter to tox option
  47         "--parallel" to parallelize jobs in the envlist (and then activate the
  48         option "--parallel-live" to display output in logs).
  49         Possible values are "auto" (equivalent to "true" for legacy),
  50         "all" or any integer. Any other value is equivalent to "false".
  51
  52
  53 Job Templates
  54 =============
  55
  56 Tox Nexus IQ CLM
  57 ----------------
  58
  59 The Nexus IQ job invokes tox and the Nexus IQ scanner to analyze packages for
  60 component lifecycle management (CLM).  Runs tox to discover the required packages,
  61 downloads the command-line interface (CLI) scanner, runs the scanner on the package
  62 list, then uploads the results to a Nexus IQ server. The project's tox.ini file must
  63 define a test environment that runs 'pip freeze' and captures the output; that
  64 environment does not need to execute any tests. For example:
  65
  66 .. code-block:: bash
  67
  68     [testenv:clm]
  69     # use pip to report dependencies with versions
  70     whitelist_externals = sh
  71     commands = sh -c 'pip freeze > requirements.txt'
  72
  73
  74 This job runs on the master branch because the basic Nexus IQ configuration
  75 does not support multi-branch.
  76
  77 :Template Names:
  78
  79     - {project-name}-tox-nexus-iq-clm
  80     - gerrit-tox-nexus-iq-clm
  81     - github-tox-nexus-iq-clm
  82
  83 :Comment Trigger: ``run-clm``
  84
  85 :Required parameters:
  86
  87     :build-node: The node to run the build on.
  88         (Commonly in defaults.yaml)
  89     :jenkins-ssh-credential: Credential to use for SSH.
  90         (Commonly in defaults.yaml)
  91     :project: The git repository name.
  92     :project-name: Prefix used to name jobs.
  93
  94 :Optional Parameters:
  95
  96     :archive-artifacts: Pattern for files to archive to the logs server
  97         (default: '\*\*/\*.log')
  98     :branch: Git branch, should be master (default: master)
  99     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 100     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 101     :cron: Cron schedule when to trigger the job. This parameter also
 102         supports multiline input via the YAML pipe | character to allow
 103         more than 1 cron timer.  (default: @weekly)
 104     :disable-job: Whether to disable the job (default: false)
 105     :gerrit_nexusiq_triggers: Override Gerrit Triggers.
 106     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 107     :github-url: URL for Github. (default: https://github.com)
 108     :java-version: Version of Java to use for the scan. (default: openjdk11)
 109     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
 110         (default is a string like 1.89.0-02, see file lf-python-jobs.yaml)
 111     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
 112         share a Nexus IQ system to avoid project name collision. We recommend
 113         inserting a trailing - dash if using this parameter.
 114         For example 'odl-'. (default: '')
 115     :nexus-target-build: Target directory or file for scanning by Nexus IQ CLI
 116         (default: "\*\*/\*")
 117     :pre-build-script: Shell script to run before tox. Useful for setting up
 118         dependencies. (default: a string with a shell comment)
 119     :python-version: Python version to invoke pip install of tox-pyenv
 120         (default: python3)
 121     :requirements-file: Name of file with output of pip freeze.
 122         (default: requirements.txt)
 123     :submodule-recursive: Whether to checkout submodules recursively.
 124         (default: true)
 125     :submodule-timeout: Timeout (in minutes) for checkout operation.
 126         (default: 10)
 127     :submodule-disable: Disable submodule checkout operation.
 128         (default: false)
 129     :tox-dir: Directory containing the project's tox.ini relative to
 130         the workspace. The default uses tox.ini at the project root.
 131         (default: '.')
 132     :tox-envs: Tox environment with the appropriate pip freeze invocation.
 133         (default: 'clm')
 134
 135 Python Snyk CLI
 136 ---------------
 137
 138 Builds the code, downloads and runs a Snyk CLI scan of the code into the Snyk dashboard.
 139
 140 :Template Names:
 141
 142     - {project-name}-python-snyk-cli-{stream}
 143     - gerrit-python-snyk-cli
 144     - github-python-snyk-cli
 145
 146 :Comment Trigger: run-snyk
 147
 148 :Required parameters:
 149
 150     :build-node:    The node to run build on.
 151     :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
 152     :snyk-token-credential-id: Snyk API token to communicate with Jenkins.
 153     :snyk-org-credential-id: Snyk organization ID.
 154
 155 :Optional parameters:
 156
 157     :branch: The branch to build against. (default: master)
 158     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 159     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 160     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 161     :pre-build-script: Shell script to execute before the Tox builder.
 162         For example, install prerequisites or move files to the repo root.
 163         (default: a string with a shell comment)
 164     :parallel: If different from false, try pass this parameter to tox option
 165         "--parallel" to parallelize jobs in the envlist (and then activate the
 166         option "--parallel-live" to display output in logs).
 167         Possible values are "auto" (equivalent to "true" for legacy),
 168         "all" or any integer. Any other value is equivalent to "false".
 169         (default: false, in series)
 170     :python-version: Python version to invoke pip install of tox-pyenv
 171         (default: python3)
 172     :snyk-cli-options: Additional Snyk CLI options. (default: '')
 173     :stream: Keyword representing a release code-name.
 174         Often the same as the branch. (default: master)
 175     :submodule-recursive: Whether to checkout submodules recursively.
 176         (default: true)
 177     :submodule-timeout: Timeout (in minutes) for checkout operation.
 178         (default: 10)
 179     :submodule-disable: Disable submodule checkout operation.
 180         (default: false)
 181     :tox-dir: Directory containing the project's tox.ini relative to
 182         the workspace. The default uses tox.ini at the project root.
 183         (default: '.')
 184     :tox-envs: Tox environments to run. If blank run everything described
 185         in tox.ini. (default: '')
 186     :gerrit_trigger_file_paths: Override file paths used to filter which file
 187         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 188         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 189
 190 Python Sonar with CLI
 191 ---------------------
 192
 193 Sonar scans for non Maven based repos. This job downloads the CLI
 194 and runs a scan to publish the report to  SonarCloud.
 195
 196 As suggested in SonarCoud's UI instructions, the job downloads and unzips
 197 the Sonar SLI and executes a sonar-scanner command to process the
 198 report.
 199
 200 For more details refer to sonar documentation:
 201
 202 https://docs.sonarcloud.io/advanced-setup/ci-based-analysis/sonarscanner-cli/
 203
 204 :Template Names:
 205
 206     - {project-name}-cli-sonar
 207     - gerrit-cli-sonar
 208     - github-cli-sonar
 209
 210 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
 211     this job manually. Do not include any other text or vote in the
 212     same comment.
 213
 214 :Required parameters:
 215
 216     :build-node: The node to run build on.
 217     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 218         get configured in defaults.yaml)
 219     :mvn-settings: The name of the settings file with credentials for the project.
 220
 221 .. comment Start ignoring WriteGoodLintBear
 222
 223 :Optional parameters:
 224
 225     :branch: Git branch, should be master (default: master)
 226     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 227     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 228     :cron: Cron schedule when to trigger the job. This parameter also
 229         supports multiline input via YAML pipe | character in cases where
 230         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 231         to run once a day)
 232     :disable-job: Whether to disable the job (default: false)
 233     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 234     :github-url: URL for Github. (default: https://github.com)
 235     :java-version: Version of Java to use for the build. (default: openjdk11)
 236     :mvn-global-settings: The name of the Maven global settings to use
 237     :mvn-goals: The Maven goal to run first. (default: validate)
 238     :mvn-version: Version of maven to use. (default: mvn35)
 239     :parallel: If different from false, try pass this parameter to tox option
 240         "--parallel" to parallelize jobs in the envlist (and then activate the
 241         option "--parallel-live" to display output in logs).
 242         Possible values are "auto" (equivalent to "true" for legacy),
 243         "all" or any integer. Any other value is equivalent to "false".
 244         (default: false, in series)
 245     :pre-build-script: Shell script to execute before the Sonar builder.
 246         For example, install prerequisites or move files to the repo root.
 247         (default: a string with a shell comment)
 248     :python-version: Python version to invoke pip install of tox-pyenv
 249         (default: python2)
 250     :sonarcloud-project-key: SonarCloud project key. (default: '')
 251     :sonarcloud-project-organization: SonarCloud project organization.
 252         (default: '')
 253     :sonarcloud-api-token-cred-id: Jenkins credential ID which has the SonarCloud API Token.
 254         This one SHOULDN'T be overwritten as per we are standarizing the credential ID for all
 255         projects (default: 'sonarcloud-api-token')
 256     :sonar-scanner-home: Sonar scanner home directory.
 257         (default: $WORKSPACE/.sonar/sonar-scanner-$SONAR_SCANNER_VERSION-linux)
 258     :sonar-scanner-opts: Sonar scanner Java options. (default: '-server')
 259     :sonar-scanner-version: Version of sonar scanner to use. (default: 4.7.0.2747)
 260     :stream: Keyword used to represent a release code-name.
 261         Often the same as the branch. (default: master)
 262     :submodule-recursive: Whether to checkout submodules recursively.
 263         (default: true)
 264     :submodule-timeout: Timeout (in minutes) for checkout operation.
 265         (default: 10)
 266     :submodule-disable: Disable submodule checkout operation.
 267         (default: false)
 268     :tox-dir: Directory containing the project's tox.ini relative to
 269         the workspace. The default uses tox.ini at the project root.
 270         (default: '.')
 271     :tox-envs: Tox environments to run. If blank run everything described
 272         in tox.ini. (default: '')
 273     :gerrit_sonar_triggers: Override Gerrit Triggers.
 274     :gerrit_trigger_file_paths: Override file paths used to filter which file
 275         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 276         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 277
 278 .. comment Stop ignoring
 279
 280 Python Sonar with Tox
 281 ---------------------
 282
 283 Sonar scans for Python based repos. This job invokes tox to run tests
 284 and gather coverage statistics from the test results, then invokes
 285 Maven to publish the results to either a Sonar server or SonarCloud.
 286
 287 **Deprecated**, new projects should use Tox Sonarqube.
 288
 289 To get the Sonar coverage results, file tox.ini must exist and contain
 290 coverage commands to run.
 291
 292 The coverage commands define the code that gets executed by the test
 293 suites.  Checking coverage does not guarantee that the tests execute
 294 properly, but it identifies code that is not executed by any test.
 295
 296 This job reuses the Sonar builders used for Java/Maven projects which
 297 run maven twice. The first invocation does nothing for Python
 298 projects, so the job uses the goal ``validate`` by default. The second
 299 invocation publishes results using the goal ``sonar:sonar`` by default.
 300
 301 For example:
 302
 303 .. code-block:: bash
 304
 305     [testenv:py3]
 306     commands =
 307             coverage run --module pytest --junitxml xunit-results.xml
 308             coverage xml --omit=".tox/py3/*","tests/*"
 309             coverage report --omit=".tox/py3/*","tests/*"
 310
 311 For more details refer to coverage and sonar documentation:
 312
 313 https://coverage.readthedocs.io/
 314
 315 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 316
 317 :Template Names:
 318
 319     - {project-name}-tox-sonar
 320     - gerrit-tox-sonar
 321     - github-tox-sonar
 322
 323 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
 324     this job manually. Do not include any other text or vote in the
 325     same comment.
 326
 327 :Required parameters:
 328
 329     :build-node: The node to run build on.
 330     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 331         get configured in defaults.yaml)
 332     :mvn-settings: The name of the settings file with credentials for the project.
 333
 334 .. comment Start ignoring WriteGoodLintBear
 335
 336 :Optional parameters:
 337
 338     :branch: Git branch, should be master (default: master)
 339     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 340     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 341     :cron: Cron schedule when to trigger the job. This parameter also
 342         supports multiline input via YAML pipe | character in cases where
 343         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 344         to run once a day)
 345     :disable-job: Whether to disable the job (default: false)
 346     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 347     :github-url: URL for Github. (default: https://github.com)
 348     :java-version: Version of Java to use for the build. (default: openjdk11)
 349     :mvn-global-settings: The name of the Maven global settings to use
 350     :mvn-goals: The Maven goal to run first. (default: validate)
 351     :mvn-version: Version of maven to use. (default: mvn35)
 352     :parallel: If different from false, try pass this parameter to tox option
 353         "--parallel" to parallelize jobs in the envlist (and then activate the
 354         option "--parallel-live" to display output in logs).
 355         Possible values are "auto" (equivalent to "true" for legacy),
 356         "all" or any integer. Any other value is equivalent to "false".
 357         (default: false, in series)
 358     :pre-build-script: Shell script to execute before the Sonar builder.
 359         For example, install prerequisites or move files to the repo root.
 360         (default: a string with a shell comment)
 361     :python-version: Python version to invoke pip install of tox-pyenv
 362         (default: python2)
 363     :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
 364         (default: false)
 365     :sonarcloud-project-key: SonarCloud project key. (default: '')
 366     :sonarcloud-project-organization: SonarCloud project organization.
 367         (default: '')
 368     :sonarcloud-api-token-cred-id: Jenkins credential ID which has the SonarCloud API Token.
 369         This one SHOULDN'T be overwritten as per we are standarizing the credential ID for all
 370         projects (default: 'sonarcloud-api-token')
 371     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 372     :stream: Keyword used to represent a release code-name.
 373         Often the same as the branch. (default: master)
 374     :submodule-recursive: Whether to checkout submodules recursively.
 375         (default: true)
 376     :submodule-timeout: Timeout (in minutes) for checkout operation.
 377         (default: 10)
 378     :submodule-disable: Disable submodule checkout operation.
 379         (default: false)
 380     :tox-dir: Directory containing the project's tox.ini relative to
 381         the workspace. The default uses tox.ini at the project root.
 382         (default: '.')
 383     :tox-envs: Tox environments to run. If blank run everything described
 384         in tox.ini. (default: '')
 385     :gerrit_sonar_triggers: Override Gerrit Triggers.
 386     :gerrit_trigger_file_paths: Override file paths used to filter which file
 387         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 388         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 389
 390 .. comment Stop ignoring
 391
 392
 393 Tox SonarQube
 394 -------------
 395
 396 The SonarQube job invokes tox to run tests and generate code-coverage
 397 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
 398 code, gather coverage data, and upload the results to a SonarQube server
 399 such as SonarCloud.io. Optionally runs a shell script before tox.
 400
 401 Requires ``SonarQube Scanner for Jenkins``
 402
 403 This job runs on the master branch because the basic Sonar configuration
 404 does not support multi-branch.
 405
 406 Plug-in configurations
 407     Manage Jenkins --> Configure System --> SonarQube servers
 408         - Name: Sonar (fixed)
 409         - Server URL: https://sonar.project.org/ or https://sonarcloud.io
 410         - Server authentication token: none for local, API token (saved as
 411           a "secret text" credential) for Sonarcloud
 412
 413     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 414         - Name: SonarQube Scanner (fixed)
 415         - Install automatically
 416         - Select latest version
 417
 418 :Template Names:
 419
 420     - {project-name}-tox-sonarqube
 421     - gerrit-tox-sonarqube
 422     - github-tox-sonarqube
 423
 424 :Comment Trigger: ``run-sonar``
 425
 426 :Required parameters:
 427
 428     :build-node: The node to run the build on.
 429         (Commonly in defaults.yaml)
 430     :jenkins-ssh-credential: Credential to use for SSH.
 431         (Commonly in defaults.yaml)
 432     :project: The git repository name.
 433     :project-name: Prefix used to name jobs.
 434
 435 .. comment Start ignoring WriteGoodLintBear
 436
 437 :Optional Parameters:
 438
 439     :archive-artifacts: Pattern for files to archive to the logs server
 440         (default: '\*\*/\*.log')
 441     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 442     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 443     :cron: Cron schedule when to trigger the job. This parameter also
 444         supports multiline input via YAML pipe | character in cases where
 445         one may want to provide more than 1 cron timer.  (default: @weekly)
 446     :disable-job: Whether to disable the job (default: false)
 447     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 448     :github-url: URL for Github. (default: https://github.com)
 449     :parallel: If different from false, try pass this parameter to tox option
 450         "--parallel" to parallelize jobs in the envlist (and then activate the
 451         option "--parallel-live" to display output in logs).
 452         Possible values are "auto" (equivalent to "true" for legacy),
 453         "all" or any integer. Any other value is equivalent to "false".
 454         (default: false, in series)
 455     :pre-build-script: Shell script to run before tox. Useful for setting up
 456         dependencies. (default: a string with a shell comment)
 457     :python-version: Python version to invoke pip install of tox-pyenv
 458         (default: python3)
 459     :sonar-additional-args: Command line arguments. (default: '')
 460     :sonar-java-opts: JVM options. For example, use option -Xmx
 461         to increase the memory size limit.  (default: '')
 462     :sonar-jdk: JDK version to use. (default: openjdk17)
 463     :sonar-project-file: The file name with Sonar configuration properties
 464         (default: sonar-project.properties)
 465     :sonar-properties: Sonar configuration properties. (default: '')
 466     :sonar-task: Sonar task to run. (default: '')
 467     :tox-dir: Directory containing the project's tox.ini relative to
 468         the workspace. The default uses tox.ini at the project root.
 469         (default: '.')
 470     :tox-envs: Tox environments to run. If blank run everything described
 471         in tox.ini. (default: '')
 472
 473 .. comment Stop ignoring
 474
 475 .. note:: A job definition must provide one of the optional parameters
 476     ``sonar-project-file`` and ``sonar-properties``; they cannot both be
 477     empty.  Set Sonar properties directly in the job definition by setting
 478     the ``sonar-project-file`` property to ``""`` and adding all properties
 479     under ``sonar-properties``.
 480
 481 :Required Sonar Properties:
 482
 483     - sonar.login: The API token for authentication at SonarCloud.
 484       Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
 485     - sonar.organization: The umbrella project name; e.g., "opendaylight".
 486       Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
 487     - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
 488     - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
 489       teams use the catenation of sonar.organization, an underscore, and
 490       sonar.projectName; e.g., "opendaylight_infrautils".
 491
 492 :Optional Sonar Properties:
 493
 494     - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
 495     - Documentation of SonarQube properties is here:
 496       https://docs.sonarqube.org/latest/analysis/overview/
 497
 498
 499 Example job definition
 500 ^^^^^^^^^^^^^^^^^^^^^^
 501
 502 The following example defines a job for a basic Python project. This definition
 503 uses configuration parameters in the umbrella project's defaults.yaml file.
 504
 505 .. code-block:: yaml
 506
 507     - project:
 508         name: my-package-sonar
 509         project: my/package
 510         project-name: my-package
 511         sonar-project-file: ""
 512         sonar-properties: |
 513             sonar.login={sonarcloud_api_token}
 514             sonar.projectKey={sonarcloud_project_organization}_{project-name}
 515             sonar.projectName={project-name}
 516             sonar.organization={sonarcloud_project_organization}
 517             sonar.sourceEncoding=UTF-8
 518             sonar.sources=mypackage
 519             sonar.exclusions=tests/*,setup.py
 520             sonar.python.coverage.reportPaths=coverage.xml
 521         jobs:
 522           - gerrit-tox-sonarqube
 523
 524
 525 Tox Verify
 526 ----------
 527
 528 Tox runner to verify a project on creation of a patch set.  This job
 529 is pyenv aware so if the image contains an installation of pyenv at
 530 /opt/pyenv it will pick it up and run Python tests with the
 531 appropriate Python versions. This job will set the following pyenv
 532 variables before running.
 533
 534 .. code:: bash
 535
 536    export PYENV_ROOT="/opt/pyenv"
 537    export PATH="$PYENV_ROOT/bin:$PATH"
 538
 539 :Template Names:
 540
 541     - {project-name}-tox-verify-{stream}
 542     - gerrit-tox-verify
 543     - github-tox-verify
 544
 545 :Comment Trigger: **recheck|reverify** post a comment with one of the
 546     triggers to launch this job manually. Do not include any other
 547     text or vote in the same comment.
 548
 549 :Required Parameters:
 550
 551     :build-node: The node to run build on.
 552     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 553         in defaults.yaml)
 554
 555 :Optional Parameters:
 556
 557     :branch: The branch to build against. (default: master)
 558     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 559     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 560     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 561     :pre-build-script: Shell script to execute before the Tox builder.
 562         For example, install prerequisites or move files to the repo root.
 563         (default: a string with a shell comment)
 564     :parallel: If different from false, try pass this parameter to tox option
 565         "--parallel" to parallelize jobs in the envlist (and then activate the
 566         option "--parallel-live" to display output in logs).
 567         Possible values are "auto" (equivalent to "true" for legacy),
 568         "all" or any integer. Any other value is equivalent to "false".
 569         (default: false, in series)
 570     :python-version: Python version to invoke pip install of tox-pyenv
 571         (default: python2)
 572     :stream: Keyword representing a release code-name.
 573         Often the same as the branch. (default: master)
 574     :submodule-recursive: Whether to checkout submodules recursively.
 575         (default: true)
 576     :submodule-timeout: Timeout (in minutes) for checkout operation.
 577         (default: 10)
 578     :submodule-disable: Disable submodule checkout operation.
 579         (default: false)
 580     :tox-dir: Directory containing the project's tox.ini relative to
 581         the workspace. The default uses tox.ini at the project root.
 582         (default: '.')
 583     :tox-envs: Tox environments to run. If blank run everything described
 584         in tox.ini. (default: '')
 585     :gerrit_trigger_file_paths: Override file paths used to filter which file
 586         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 587         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 588
 589
 590 Tox Merge
 591 ---------
 592
 593 Tox runner to verify a project after merge of a patch set.  This job
 594 is pyenv aware so if the image contains an installation of pyenv at
 595 /opt/pyenv it will pick it up and run Python tests with the
 596 appropriate Python versions. This job will set the following pyenv
 597 variables before running.
 598
 599 .. code:: bash
 600
 601    export PYENV_ROOT="/opt/pyenv"
 602    export PATH="$PYENV_ROOT/bin:$PATH"
 603
 604 :Template Names:
 605
 606     - {project-name}-tox-merge-{stream}
 607     - gerrit-tox-merge
 608     - github-tox-merge
 609
 610 :Comment Trigger: **remerge** post a comment with the trigger to launch
 611     this job manually. Do not include any other text or vote in the
 612     same comment.
 613
 614 :Required Parameters:
 615
 616     :build-node: The node to run build on.
 617     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 618         in defaults.yaml)
 619
 620 :Optional Parameters:
 621
 622     :branch: The branch to build against. (default: master)
 623     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 624     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 625     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 626     :pre-build-script: Shell script to execute before the CLM builder.
 627         For example, install prerequisites or move files to the repo root.
 628         (default: a string with a shell comment)
 629     :python-version: Python version to invoke pip install of tox-pyenv
 630         (default: python2)
 631     :stream: Keyword representing a release code-name.
 632         Often the same as the branch. (default: master)
 633     :submodule-recursive: Whether to checkout submodules recursively.
 634         (default: true)
 635     :submodule-timeout: Timeout (in minutes) for checkout operation.
 636         (default: 10)
 637     :submodule-disable: Disable submodule checkout operation.
 638         (default: false)
 639     :tox-dir: Directory containing the project's tox.ini relative to
 640         the workspace. The default uses tox.ini at the project root.
 641         (default: '.')
 642     :tox-envs: Tox environments to run. If blank run everything described
 643         in tox.ini. (default: '')
 644     :gerrit_trigger_file_paths: Override file paths used to filter which file
 645         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 646         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 647
 648
 649 PyPI Merge
 650 ----------
 651
 652 Creates and uploads package distribution files on merge of a patch set.
 653 Runs tox, builds a source distribution and (optionally) a binary
 654 distribution, and uploads the distribution(s) to a PyPI repository.
 655 The project git repository must have a setup.py file
 656 with configuration for packaging the component.
 657
 658 Projects can choose **either** this template to publish on merge,
 659 **or** the Stage template to publish on command.
 660
 661 This job should use a staging repository like testpypi.python.org,
 662 which sets up use of release jobs to promote the distributions later.
 663 This job can also use a public release area like the global PyPI
 664 repository if the release process is not needed. These PyPI
 665 repositories allow upload of a package at a specific version once,
 666 they do not allow overwrite of a package.  This means that a merge job
 667 will fail in the upload step if the package version already exists in
 668 the target repository.
 669
 670 The tox runner is pyenv aware so if the image contains an installation
 671 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 672 the appropriate Python versions. The tox runner sets the following
 673 pyenv variables before running.
 674
 675 .. code:: bash
 676
 677    export PYENV_ROOT="/opt/pyenv"
 678    export PATH="$PYENV_ROOT/bin:$PATH"
 679
 680 See the recommended directory layout documented in the PyPI Verify job.
 681
 682 Jobs using this PyPI template depend on a .pypirc configuration file
 683 in the Jenkins builder home directory. An example appears next that uses
 684 API tokens. Note that in the [pypi] entry the repository key-value pair
 685 is optional, it defaults to pypi.org.
 686
 687 .. code-block:: bash
 688
 689     [distutils] # this tells distutils what package indexes you can push to
 690     index-servers = pypi-test pypi
 691
 692     [pypi-test]
 693     repository: https://test.pypi.org/legacy/
 694     username: __token__
 695     password: pypi-test-api-token-goes-here
 696
 697     [pypi]
 698     username: __token__
 699     password: pypi-api-token-goes-here
 700
 701
 702 :Template Names:
 703
 704     - {project-name}-pypi-merge-{stream}
 705     - gerrit-pypi-merge
 706     - github-pypi-merge
 707
 708 :Comment Trigger: **remerge** post a comment with the trigger to launch
 709     this job manually. Do not include any other text or vote in the
 710     same comment.
 711
 712 :Required Parameters:
 713
 714     :build-node: The node to run the build on.
 715     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 716         in defaults.yaml)
 717     :mvn-settings: The settings file with credentials for the project
 718     :project: Git repository name
 719     :project-name: Jenkins job name prefix
 720
 721 :Optional Parameters:
 722
 723     :branch: The branch to build against. (default: master)
 724     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 725     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 726     :cron: Cron schedule when to trigger the job. Supports regular builds.
 727         Not useful when publishing to pypi.org because that rejects a package
 728         if the version exists. (default: empty)
 729     :disable-job: Whether to disable the job (default: false)
 730     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 731     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 732     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 733     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 734     :mvn-version: Version of maven to use. (default: mvn35)
 735     :parallel: If different from false, try pass this parameter to tox option
 736         "--parallel" to parallelize jobs in the envlist (and then activate the
 737         option "--parallel-live" to display output in logs).
 738         Possible values are "auto" (equivalent to "true" for legacy),
 739         "all" or any integer. Any other value is equivalent to "false".
 740         (default: false, in series)
 741     :pre-build-script: Shell script to execute before the tox builder. For
 742         example, install system prerequisites. (default: a shell comment)
 743     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 744         ideally a server like test.pypi.org. (default: pypi-test)
 745     :python-version: Python version to invoke pip install of tox-pyenv
 746         (default: python3)
 747     :stream: Keyword representing a release code-name.
 748         Often the same as the branch. (default: master)
 749     :submodule-recursive: Whether to checkout submodules recursively.
 750         (default: true)
 751     :submodule-timeout: Timeout (in minutes) for checkout operation.
 752         (default: 10)
 753     :submodule-disable: Disable submodule checkout operation.
 754         (default: false)
 755     :tox-dir: Directory containing the project's tox.ini relative to
 756         the workspace. The default uses tox.ini at the project root.
 757         (default: '.')
 758     :tox-envs: Tox environments to run. If blank run everything described
 759         in tox.ini. (default: '')
 760     :gerrit_trigger_file_paths: Override file paths used to filter which file
 761         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 762         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 763
 764
 765 PyPI Stage
 766 ----------
 767
 768 Creates and uploads package distribution files on receipt of a comment.
 769 Runs tox, builds a source distribution and (optionally) a binary
 770 distribution, and uploads the distribution(s) to a PyPI repository.
 771 The project git repository must have a setup.py file with configuration
 772 for packaging the component.
 773
 774 Projects can choose **either** this template to publish on command,
 775 **or** the Merge template to publish on merge.
 776
 777 This job should use a staging repository like testpypi.python.org,
 778 which sets up use of release jobs to promote the distributions later.
 779 This job can also use a public release area like the global PyPI
 780 repository if the release process is not needed. These PyPI
 781 repositories allow upload of a package at a specific version once,
 782 they do not allow overwrite of a package.  This means that a job
 783 will fail in the upload step if the package version already exists in
 784 the target repository.
 785
 786 The tox runner is pyenv aware so if the image contains an installation
 787 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 788 the appropriate Python versions. The tox runner sets the following
 789 pyenv variables before running.
 790
 791 .. code:: bash
 792
 793    export PYENV_ROOT="/opt/pyenv"
 794    export PATH="$PYENV_ROOT/bin:$PATH"
 795
 796 See the recommended directory layout documented in the PyPI Verify job.
 797
 798 Jobs using this PyPI template depend on a .pypirc configuration file
 799 in the Jenkins builder home directory. An example appears next that uses
 800 API tokens. Note that in the [pypi] entry the repository key-value pair
 801 is optional, it defaults to pypi.org.
 802
 803 .. code-block:: bash
 804
 805     [distutils] # this tells distutils what package indexes you can push to
 806     index-servers = pypi-test pypi
 807
 808     [pypi-test]
 809     repository: https://test.pypi.org/legacy/
 810     username: __token__
 811     password: pypi-test-api-token-goes-here
 812
 813     [pypi]
 814     username: __token__
 815     password: pypi-api-token-goes-here
 816
 817
 818 :Template Names:
 819
 820     - {project-name}-pypi-stage-{stream}
 821     - gerrit-pypi-stage
 822     - github-pypi-stage
 823
 824 :Comment Trigger: **stage-release** post a comment with the trigger to launch
 825     this job manually. Do not include any other text or vote in the
 826     same comment.
 827
 828 :Required Parameters:
 829
 830     :build-node: The node to run the build on.
 831     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 832         in defaults.yaml)
 833     :mvn-settings: The settings file with credentials for the project
 834     :project: Git repository name
 835     :project-name: Jenkins job name prefix
 836
 837 :Optional Parameters:
 838
 839     :branch: The branch to build against. (default: master)
 840     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 841     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 842     :cron: Cron schedule when to trigger the job. Supports regular builds.
 843         Not useful when publishing to pypi.org because that rejects a package
 844         if the version exists. (default: empty)
 845     :disable-job: Whether to disable the job (default: false)
 846     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 847     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 848     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 849     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 850     :mvn-version: Version of maven to use. (default: mvn35)
 851     :parallel: If different from false, try pass this parameter to tox option
 852         "--parallel" to parallelize jobs in the envlist (and then activate the
 853         option "--parallel-live" to display output in logs).
 854         Possible values are "auto" (equivalent to "true" for legacy),
 855         "all" or any integer. Any other value is equivalent to "false".
 856         (default: false, in series)
 857     :pre-build-script: Shell script to execute before the tox builder. For
 858         example, install system prerequisites. (default: a shell comment)
 859     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 860         ideally a server like test.pypi.org. (default: pypi-test)
 861     :python-version: Python version to invoke pip install of tox-pyenv
 862         (default: python3)
 863     :stream: Keyword representing a release code-name.
 864         Often the same as the branch. (default: master)
 865     :submodule-recursive: Whether to checkout submodules recursively.
 866         (default: true)
 867     :submodule-timeout: Timeout (in minutes) for checkout operation.
 868         (default: 10)
 869     :submodule-disable: Disable submodule checkout operation.
 870         (default: false)
 871     :tox-dir: Directory containing the project's tox.ini relative to
 872         the workspace. The default uses tox.ini at the project root.
 873         (default: '.')
 874     :tox-envs: Tox environments to run. If blank run everything described
 875         in tox.ini. (default: '')
 876     :gerrit_trigger_file_paths: Override file paths used to filter which file
 877         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 878         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 879
 880 PyPI Verify
 881 -----------
 882
 883 Verifies a Python library project on creation of a patch set. Runs tox
 884 then builds a source distribution and (optionally) a binary
 885 distribution. The project repository must have a setup.py file with
 886 configuration for packaging the component.
 887
 888 Installable package projects should use the directory layout shown
 889 below. All Python files are in a repo subdirectory separate from
 890 non-Python files like documentation. This layout allows highly
 891 specific build-job triggers in Jenkins using the subdirectory
 892 paths. For example, a PyPI publisher job should not run on a non-Python
 893 file change such as documentation, because the job cannot upload the
 894 same package twice.
 895
 896 To make the document files available for building a Python package
 897 long description in setup.py, add a symbolic link "docs" in the
 898 package subdirectory pointing to the top-level docs directory.
 899
 900 .. code-block:: bash
 901
 902     git-repo-name/
 903     │
 904     ├── docs/
 905     │   ├── index.rst
 906     │   └── release-notes.rst
 907     │
 908     ├── helloworld-package/
 909     │   │
 910     │   └── helloworld/
 911     │   │   ├── __init__.py
 912     │   │   ├── helloworld.py
 913     │   │   └── helpers.py
 914     │   │
 915     │   ├── tests/
 916     │   │   ├── helloworld_tests.py
 917     │   │   └── helloworld_mocks.py
 918     │   │
 919     │   ├── requirements.txt
 920     │   └── setup.py
 921     │   └── tox.ini
 922     │
 923     ├── releases/
 924     │   └── pypi-helloworld.yaml
 925     │
 926     ├── .gitignore
 927     ├── LICENSE
 928     └── README.md
 929
 930
 931 The tox runner is pyenv aware so if the image contains an installation
 932 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 933 the appropriate Python versions. The tox runner sets the following
 934 pyenv variables before running.
 935
 936 .. code:: bash
 937
 938    export PYENV_ROOT="/opt/pyenv"
 939    export PATH="$PYENV_ROOT/bin:$PATH"
 940
 941 :Template Names:
 942
 943     - {project-name}-pypi-verify-{stream}
 944     - gerrit-pypi-verify
 945     - github-pypi-verify
 946
 947 :Comment Trigger: **recheck|reverify** post a comment with one of the
 948     triggers to launch this job manually. Do not include any other
 949     text or vote in the same comment.
 950
 951 :Required Parameters:
 952
 953     :build-node: The node to run the build on.
 954     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 955         in defaults.yaml)
 956     :mvn-settings: The settings file with credentials for the project
 957     :project: Git repository name
 958     :project-name: Jenkins job name prefix
 959
 960 :Optional Parameters:
 961
 962     :branch: The branch to build against. (default: master)
 963     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 964     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 965     :disable-job: Whether to disable the job (default: false)
 966     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 967     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 968     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 969     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 970     :mvn-version: Version of maven to use. (default: mvn35)
 971     :parallel: If different from false, try pass this parameter to tox option
 972         "--parallel" to parallelize jobs in the envlist (and then activate the
 973         option "--parallel-live" to display output in logs).
 974         Possible values are "auto" (equivalent to "true" for legacy),
 975         "all" or any integer. Any other value is equivalent to "false".
 976         (default: false, in series)
 977     :pre-build-script: Shell script to execute before the tox builder. For
 978         example, install system prerequisites. (default: a shell comment)
 979     :python-version: Python version to invoke pip install of tox-pyenv
 980         (default: python3)
 981     :stream: Keyword representing a release code-name.
 982         Often the same as the branch. (default: master)
 983     :submodule-recursive: Whether to checkout submodules recursively.
 984         (default: true)
 985     :submodule-timeout: Timeout (in minutes) for checkout operation.
 986         (default: 10)
 987     :submodule-disable: Disable submodule checkout operation.
 988         (default: false)
 989     :tox-dir: Directory containing the project's tox.ini relative to
 990         the workspace. The default uses tox.ini at the project root.
 991         (default: '.')
 992     :tox-envs: Tox environments to run. If blank run everything described
 993         in tox.ini. (default: '')
 994     :gerrit_trigger_file_paths: Override file paths used to filter which file
 995         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 996         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit