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     :java-version: JDK version to use. (default: openjdk17)
 450     :parallel: If different from false, try pass this parameter to tox option
 451         "--parallel" to parallelize jobs in the envlist (and then activate the
 452         option "--parallel-live" to display output in logs).
 453         Possible values are "auto" (equivalent to "true" for legacy),
 454         "all" or any integer. Any other value is equivalent to "false".
 455         (default: false, in series)
 456     :pre-build-script: Shell script to run before tox. Useful for setting up
 457         dependencies. (default: a string with a shell comment)
 458     :python-version: Python version to invoke pip install of tox-pyenv
 459         (default: python3)
 460     :sonar-additional-args: Command line arguments. (default: '')
 461     :sonar-java-opts: JVM options. For example, use option -Xmx
 462         to increase the memory size limit.  (default: '')
 463     :sonar-jdk: JDK version to use. (default: openjdk17)
 464     :sonar-project-file: The file name with Sonar configuration properties
 465         (default: sonar-project.properties)
 466     :sonar-properties: Sonar configuration properties. (default: '')
 467     :sonar-task: Sonar task to run. (default: '')
 468     :tox-dir: Directory containing the project's tox.ini relative to
 469         the workspace. The default uses tox.ini at the project root.
 470         (default: '.')
 471     :tox-envs: Tox environments to run. If blank run everything described
 472         in tox.ini. (default: '')
 473
 474 .. comment Stop ignoring
 475
 476 .. note:: A job definition must provide one of the optional parameters
 477     ``sonar-project-file`` and ``sonar-properties``; they cannot both be
 478     empty.  Set Sonar properties directly in the job definition by setting
 479     the ``sonar-project-file`` property to ``""`` and adding all properties
 480     under ``sonar-properties``.
 481
 482 :Required Sonar Properties:
 483
 484     - sonar.login: The API token for authentication at SonarCloud.
 485       Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
 486     - sonar.organization: The umbrella project name; e.g., "opendaylight".
 487       Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
 488     - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
 489     - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
 490       teams use the catenation of sonar.organization, an underscore, and
 491       sonar.projectName; e.g., "opendaylight_infrautils".
 492
 493 :Optional Sonar Properties:
 494
 495     - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
 496     - Documentation of SonarQube properties is here:
 497       https://docs.sonarqube.org/latest/analysis/overview/
 498
 499
 500 Example job definition
 501 ^^^^^^^^^^^^^^^^^^^^^^
 502
 503 The following example defines a job for a basic Python project. This definition
 504 uses configuration parameters in the umbrella project's defaults.yaml file.
 505
 506 .. code-block:: yaml
 507
 508     - project:
 509         name: my-package-sonar
 510         project: my/package
 511         project-name: my-package
 512         sonar-project-file: ""
 513         sonar-properties: |
 514             sonar.login={sonarcloud_api_token}
 515             sonar.projectKey={sonarcloud_project_organization}_{project-name}
 516             sonar.projectName={project-name}
 517             sonar.organization={sonarcloud_project_organization}
 518             sonar.sourceEncoding=UTF-8
 519             sonar.sources=mypackage
 520             sonar.exclusions=tests/*,setup.py
 521             sonar.python.coverage.reportPaths=coverage.xml
 522         jobs:
 523           - gerrit-tox-sonarqube
 524
 525
 526 Tox Verify
 527 ----------
 528
 529 Tox runner to verify a project on creation of a patch set.  This job
 530 is pyenv aware so if the image contains an installation of pyenv at
 531 /opt/pyenv it will pick it up and run Python tests with the
 532 appropriate Python versions. This job will set the following pyenv
 533 variables before running.
 534
 535 .. code:: bash
 536
 537    export PYENV_ROOT="/opt/pyenv"
 538    export PATH="$PYENV_ROOT/bin:$PATH"
 539
 540 :Template Names:
 541
 542     - {project-name}-tox-verify-{stream}
 543     - gerrit-tox-verify
 544     - github-tox-verify
 545
 546 :Comment Trigger: **recheck|reverify** post a comment with one of the
 547     triggers to launch this job manually. Do not include any other
 548     text or vote in the same comment.
 549
 550 :Required Parameters:
 551
 552     :build-node: The node to run build on.
 553     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 554         in defaults.yaml)
 555
 556 :Optional Parameters:
 557
 558     :branch: The branch to build against. (default: master)
 559     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 560     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 561     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 562     :pre-build-script: Shell script to execute before the Tox builder.
 563         For example, install prerequisites or move files to the repo root.
 564         (default: a string with a shell comment)
 565     :parallel: If different from false, try pass this parameter to tox option
 566         "--parallel" to parallelize jobs in the envlist (and then activate the
 567         option "--parallel-live" to display output in logs).
 568         Possible values are "auto" (equivalent to "true" for legacy),
 569         "all" or any integer. Any other value is equivalent to "false".
 570         (default: false, in series)
 571     :python-version: Python version to invoke pip install of tox-pyenv
 572         (default: python2)
 573     :stream: Keyword representing a release code-name.
 574         Often the same as the branch. (default: master)
 575     :submodule-recursive: Whether to checkout submodules recursively.
 576         (default: true)
 577     :submodule-timeout: Timeout (in minutes) for checkout operation.
 578         (default: 10)
 579     :submodule-disable: Disable submodule checkout operation.
 580         (default: false)
 581     :tox-dir: Directory containing the project's tox.ini relative to
 582         the workspace. The default uses tox.ini at the project root.
 583         (default: '.')
 584     :tox-envs: Tox environments to run. If blank run everything described
 585         in tox.ini. (default: '')
 586     :gerrit_trigger_file_paths: Override file paths used to filter which file
 587         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 588         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 589
 590
 591 Tox Merge
 592 ---------
 593
 594 Tox runner to verify a project after merge of a patch set.  This job
 595 is pyenv aware so if the image contains an installation of pyenv at
 596 /opt/pyenv it will pick it up and run Python tests with the
 597 appropriate Python versions. This job will set the following pyenv
 598 variables before running.
 599
 600 .. code:: bash
 601
 602    export PYENV_ROOT="/opt/pyenv"
 603    export PATH="$PYENV_ROOT/bin:$PATH"
 604
 605 :Template Names:
 606
 607     - {project-name}-tox-merge-{stream}
 608     - gerrit-tox-merge
 609     - github-tox-merge
 610
 611 :Comment Trigger: **remerge** post a comment with the trigger to launch
 612     this job manually. Do not include any other text or vote in the
 613     same comment.
 614
 615 :Required Parameters:
 616
 617     :build-node: The node to run build on.
 618     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 619         in defaults.yaml)
 620
 621 :Optional Parameters:
 622
 623     :branch: The branch to build against. (default: master)
 624     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 625     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 626     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 627     :pre-build-script: Shell script to execute before the CLM builder.
 628         For example, install prerequisites or move files to the repo root.
 629         (default: a string with a shell comment)
 630     :python-version: Python version to invoke pip install of tox-pyenv
 631         (default: python2)
 632     :stream: Keyword representing a release code-name.
 633         Often the same as the branch. (default: master)
 634     :submodule-recursive: Whether to checkout submodules recursively.
 635         (default: true)
 636     :submodule-timeout: Timeout (in minutes) for checkout operation.
 637         (default: 10)
 638     :submodule-disable: Disable submodule checkout operation.
 639         (default: false)
 640     :tox-dir: Directory containing the project's tox.ini relative to
 641         the workspace. The default uses tox.ini at the project root.
 642         (default: '.')
 643     :tox-envs: Tox environments to run. If blank run everything described
 644         in tox.ini. (default: '')
 645     :gerrit_trigger_file_paths: Override file paths used to filter which file
 646         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 647         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 648
 649
 650 PyPI Merge
 651 ----------
 652
 653 Creates and uploads package distribution files on merge of a patch set.
 654 Runs tox, builds a source distribution and (optionally) a binary
 655 distribution, and uploads the distribution(s) to a PyPI repository.
 656 The project git repository must have a setup.py file
 657 with configuration for packaging the component.
 658
 659 Projects can choose **either** this template to publish on merge,
 660 **or** the Stage template to publish on command.
 661
 662 This job should use a staging repository like testpypi.python.org,
 663 which sets up use of release jobs to promote the distributions later.
 664 This job can also use a public release area like the global PyPI
 665 repository if the release process is not needed. These PyPI
 666 repositories allow upload of a package at a specific version once,
 667 they do not allow overwrite of a package.  This means that a merge job
 668 will fail in the upload step if the package version already exists in
 669 the target repository.
 670
 671 The tox runner is pyenv aware so if the image contains an installation
 672 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 673 the appropriate Python versions. The tox runner sets the following
 674 pyenv variables before running.
 675
 676 .. code:: bash
 677
 678    export PYENV_ROOT="/opt/pyenv"
 679    export PATH="$PYENV_ROOT/bin:$PATH"
 680
 681 See the recommended directory layout documented in the PyPI Verify job.
 682
 683 Jobs using this PyPI template depend on a .pypirc configuration file
 684 in the Jenkins builder home directory. An example appears next that uses
 685 API tokens. Note that in the [pypi] entry the repository key-value pair
 686 is optional, it defaults to pypi.org.
 687
 688 .. code-block:: bash
 689
 690     [distutils] # this tells distutils what package indexes you can push to
 691     index-servers = pypi-test pypi
 692
 693     [pypi-test]
 694     repository: https://test.pypi.org/legacy/
 695     username: __token__
 696     password: pypi-test-api-token-goes-here
 697
 698     [pypi]
 699     username: __token__
 700     password: pypi-api-token-goes-here
 701
 702
 703 :Template Names:
 704
 705     - {project-name}-pypi-merge-{stream}
 706     - gerrit-pypi-merge
 707     - github-pypi-merge
 708
 709 :Comment Trigger: **remerge** post a comment with the trigger to launch
 710     this job manually. Do not include any other text or vote in the
 711     same comment.
 712
 713 :Required Parameters:
 714
 715     :build-node: The node to run the build on.
 716     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 717         in defaults.yaml)
 718     :mvn-settings: The settings file with credentials for the project
 719     :project: Git repository name
 720     :project-name: Jenkins job name prefix
 721
 722 :Optional Parameters:
 723
 724     :branch: The branch to build against. (default: master)
 725     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 726     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 727     :cron: Cron schedule when to trigger the job. Supports regular builds.
 728         Not useful when publishing to pypi.org because that rejects a package
 729         if the version exists. (default: empty)
 730     :disable-job: Whether to disable the job (default: false)
 731     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 732     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 733     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 734     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 735     :mvn-version: Version of maven to use. (default: mvn35)
 736     :parallel: If different from false, try pass this parameter to tox option
 737         "--parallel" to parallelize jobs in the envlist (and then activate the
 738         option "--parallel-live" to display output in logs).
 739         Possible values are "auto" (equivalent to "true" for legacy),
 740         "all" or any integer. Any other value is equivalent to "false".
 741         (default: false, in series)
 742     :pre-build-script: Shell script to execute before the tox builder. For
 743         example, install system prerequisites. (default: a shell comment)
 744     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 745         ideally a server like test.pypi.org. (default: pypi-test)
 746     :python-version: Python version to invoke pip install of tox-pyenv
 747         (default: python3)
 748     :stream: Keyword representing a release code-name.
 749         Often the same as the branch. (default: master)
 750     :submodule-recursive: Whether to checkout submodules recursively.
 751         (default: true)
 752     :submodule-timeout: Timeout (in minutes) for checkout operation.
 753         (default: 10)
 754     :submodule-disable: Disable submodule checkout operation.
 755         (default: false)
 756     :tox-dir: Directory containing the project's tox.ini relative to
 757         the workspace. The default uses tox.ini at the project root.
 758         (default: '.')
 759     :tox-envs: Tox environments to run. If blank run everything described
 760         in tox.ini. (default: '')
 761     :gerrit_trigger_file_paths: Override file paths used to filter which file
 762         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 763         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 764
 765
 766 PyPI Stage
 767 ----------
 768
 769 Creates and uploads package distribution files on receipt of a comment.
 770 Runs tox, builds a source distribution and (optionally) a binary
 771 distribution, and uploads the distribution(s) to a PyPI repository.
 772 The project git repository must have a setup.py file with configuration
 773 for packaging the component.
 774
 775 Projects can choose **either** this template to publish on command,
 776 **or** the Merge template to publish on merge.
 777
 778 This job should use a staging repository like testpypi.python.org,
 779 which sets up use of release jobs to promote the distributions later.
 780 This job can also use a public release area like the global PyPI
 781 repository if the release process is not needed. These PyPI
 782 repositories allow upload of a package at a specific version once,
 783 they do not allow overwrite of a package.  This means that a job
 784 will fail in the upload step if the package version already exists in
 785 the target repository.
 786
 787 The tox runner is pyenv aware so if the image contains an installation
 788 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 789 the appropriate Python versions. The tox runner sets the following
 790 pyenv variables before running.
 791
 792 .. code:: bash
 793
 794    export PYENV_ROOT="/opt/pyenv"
 795    export PATH="$PYENV_ROOT/bin:$PATH"
 796
 797 See the recommended directory layout documented in the PyPI Verify job.
 798
 799 Jobs using this PyPI template depend on a .pypirc configuration file
 800 in the Jenkins builder home directory. An example appears next that uses
 801 API tokens. Note that in the [pypi] entry the repository key-value pair
 802 is optional, it defaults to pypi.org.
 803
 804 .. code-block:: bash
 805
 806     [distutils] # this tells distutils what package indexes you can push to
 807     index-servers = pypi-test pypi
 808
 809     [pypi-test]
 810     repository: https://test.pypi.org/legacy/
 811     username: __token__
 812     password: pypi-test-api-token-goes-here
 813
 814     [pypi]
 815     username: __token__
 816     password: pypi-api-token-goes-here
 817
 818
 819 :Template Names:
 820
 821     - {project-name}-pypi-stage-{stream}
 822     - gerrit-pypi-stage
 823     - github-pypi-stage
 824
 825 :Comment Trigger: **stage-release** post a comment with the trigger to launch
 826     this job manually. Do not include any other text or vote in the
 827     same comment.
 828
 829 :Required Parameters:
 830
 831     :build-node: The node to run the build on.
 832     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 833         in defaults.yaml)
 834     :mvn-settings: The settings file with credentials for the project
 835     :project: Git repository name
 836     :project-name: Jenkins job name prefix
 837
 838 :Optional Parameters:
 839
 840     :branch: The branch to build against. (default: master)
 841     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 842     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 843     :cron: Cron schedule when to trigger the job. Supports regular builds.
 844         Not useful when publishing to pypi.org because that rejects a package
 845         if the version exists. (default: empty)
 846     :disable-job: Whether to disable the job (default: false)
 847     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 848     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 849     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 850     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 851     :mvn-version: Version of maven to use. (default: mvn35)
 852     :parallel: If different from false, try pass this parameter to tox option
 853         "--parallel" to parallelize jobs in the envlist (and then activate the
 854         option "--parallel-live" to display output in logs).
 855         Possible values are "auto" (equivalent to "true" for legacy),
 856         "all" or any integer. Any other value is equivalent to "false".
 857         (default: false, in series)
 858     :pre-build-script: Shell script to execute before the tox builder. For
 859         example, install system prerequisites. (default: a shell comment)
 860     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 861         ideally a server like test.pypi.org. (default: pypi-test)
 862     :python-version: Python version to invoke pip install of tox-pyenv
 863         (default: python3)
 864     :stream: Keyword representing a release code-name.
 865         Often the same as the branch. (default: master)
 866     :submodule-recursive: Whether to checkout submodules recursively.
 867         (default: true)
 868     :submodule-timeout: Timeout (in minutes) for checkout operation.
 869         (default: 10)
 870     :submodule-disable: Disable submodule checkout operation.
 871         (default: false)
 872     :tox-dir: Directory containing the project's tox.ini relative to
 873         the workspace. The default uses tox.ini at the project root.
 874         (default: '.')
 875     :tox-envs: Tox environments to run. If blank run everything described
 876         in tox.ini. (default: '')
 877     :gerrit_trigger_file_paths: Override file paths used to filter which file
 878         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 879         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
 880
 881 PyPI Verify
 882 -----------
 883
 884 Verifies a Python library project on creation of a patch set. Runs tox
 885 then builds a source distribution and (optionally) a binary
 886 distribution. The project repository must have a setup.py file with
 887 configuration for packaging the component.
 888
 889 Installable package projects should use the directory layout shown
 890 below. All Python files are in a repo subdirectory separate from
 891 non-Python files like documentation. This layout allows highly
 892 specific build-job triggers in Jenkins using the subdirectory
 893 paths. For example, a PyPI publisher job should not run on a non-Python
 894 file change such as documentation, because the job cannot upload the
 895 same package twice.
 896
 897 To make the document files available for building a Python package
 898 long description in setup.py, add a symbolic link "docs" in the
 899 package subdirectory pointing to the top-level docs directory.
 900
 901 .. code-block:: bash
 902
 903     git-repo-name/
 904     │
 905     ├── docs/
 906     │   ├── index.rst
 907     │   └── release-notes.rst
 908     │
 909     ├── helloworld-package/
 910     │   │
 911     │   └── helloworld/
 912     │   │   ├── __init__.py
 913     │   │   ├── helloworld.py
 914     │   │   └── helpers.py
 915     │   │
 916     │   ├── tests/
 917     │   │   ├── helloworld_tests.py
 918     │   │   └── helloworld_mocks.py
 919     │   │
 920     │   ├── requirements.txt
 921     │   └── setup.py
 922     │   └── tox.ini
 923     │
 924     ├── releases/
 925     │   └── pypi-helloworld.yaml
 926     │
 927     ├── .gitignore
 928     ├── LICENSE
 929     └── README.md
 930
 931
 932 The tox runner is pyenv aware so if the image contains an installation
 933 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 934 the appropriate Python versions. The tox runner sets the following
 935 pyenv variables before running.
 936
 937 .. code:: bash
 938
 939    export PYENV_ROOT="/opt/pyenv"
 940    export PATH="$PYENV_ROOT/bin:$PATH"
 941
 942 :Template Names:
 943
 944     - {project-name}-pypi-verify-{stream}
 945     - gerrit-pypi-verify
 946     - github-pypi-verify
 947
 948 :Comment Trigger: **recheck|reverify** post a comment with one of the
 949     triggers to launch this job manually. Do not include any other
 950     text or vote in the same comment.
 951
 952 :Required Parameters:
 953
 954     :build-node: The node to run the build on.
 955     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 956         in defaults.yaml)
 957     :mvn-settings: The settings file with credentials for the project
 958     :project: Git repository name
 959     :project-name: Jenkins job name prefix
 960
 961 :Optional Parameters:
 962
 963     :branch: The branch to build against. (default: master)
 964     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 965     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 966     :disable-job: Whether to disable the job (default: false)
 967     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 968     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 969     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 970     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 971     :mvn-version: Version of maven to use. (default: mvn35)
 972     :parallel: If different from false, try pass this parameter to tox option
 973         "--parallel" to parallelize jobs in the envlist (and then activate the
 974         option "--parallel-live" to display output in logs).
 975         Possible values are "auto" (equivalent to "true" for legacy),
 976         "all" or any integer. Any other value is equivalent to "false".
 977         (default: false, in series)
 978     :pre-build-script: Shell script to execute before the tox builder. For
 979         example, install system prerequisites. (default: a shell comment)
 980     :python-version: Python version to invoke pip install of tox-pyenv
 981         (default: python3)
 982     :stream: Keyword representing a release code-name.
 983         Often the same as the branch. (default: master)
 984     :submodule-recursive: Whether to checkout submodules recursively.
 985         (default: true)
 986     :submodule-timeout: Timeout (in minutes) for checkout operation.
 987         (default: 10)
 988     :submodule-disable: Disable submodule checkout operation.
 989         (default: false)
 990     :tox-dir: Directory containing the project's tox.ini relative to
 991         the workspace. The default uses tox.ini at the project root.
 992         (default: '.')
 993     :tox-envs: Tox environments to run. If blank run everything described
 994         in tox.ini. (default: '')
 995     :gerrit_trigger_file_paths: Override file paths used to filter which file
 996         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 997         https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit