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