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