docs/jjb/lf-python-jobs.rst

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