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