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 tox with the options "--parallel auto"
  47         and "--parallel-live" to parallelize jobs in the envlist;
  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 This job reuses the Sonar builders used for Java/Maven projects which
 148 run maven twice. The first invocation does nothing for Python
 149 projects, so the job uses the goal ``validate`` by default. The second
 150 invocation publishes results using the goal ``sonar:sonar`` by default.
 151
 152 For example:
 153
 154 .. code-block:: bash
 155
 156     [testenv:py3]
 157     commands =
 158             coverage run --module pytest --junitxml xunit-results.xml
 159             coverage xml --omit=".tox/py3/*","tests/*"
 160             coverage report --omit=".tox/py3/*","tests/*"
 161
 162 For more details refer to coverage and sonar documentation:
 163
 164 https://coverage.readthedocs.io/
 165
 166 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 167
 168 :Template Names:
 169
 170     - {project-name}-tox-sonar
 171     - gerrit-tox-sonar
 172     - github-tox-sonar
 173
 174 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
 175     this job manually. Do not include any other text or vote in the
 176     same comment.
 177
 178 :Required parameters:
 179
 180     :build-node: The node to run build on.
 181     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 182         get configured in defaults.yaml)
 183     :mvn-settings: The name of the settings file with credentials for the project.
 184
 185 .. comment Start ignoring WriteGoodLintBear
 186
 187 :Optional parameters:
 188
 189     :branch: Git branch, should be master (default: master)
 190     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 191     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 192     :cron: Cron schedule when to trigger the job. This parameter also
 193         supports multiline input via YAML pipe | character in cases where
 194         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 195         to run once a day)
 196     :disable-job: Whether to disable the job (default: false)
 197     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 198     :github-url: URL for Github. (default: https://github.com)
 199     :java-version: Version of Java to use for the build. (default: openjdk8)
 200     :mvn-global-settings: The name of the Maven global settings to use
 201     :mvn-goals: The Maven goal to run first. (default: validate)
 202     :mvn-version: Version of maven to use. (default: mvn35)
 203     :parallel: Boolean indicator for tox to run tests in parallel or series.
 204         (default: false, in series)
 205         If true use tox with the options "--parallel auto" and "--parallel-live"
 206         to parallelize jobs in the envlist.
 207     :pre-build-script: Shell script to execute before the Sonar builder.
 208         For example, install prerequisites or move files to the repo root.
 209         (default: a string with a shell comment)
 210     :python-version: Python version to invoke pip install of tox-pyenv
 211         (default: python2)
 212     :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
 213         (default: false)
 214     :sonarcloud-project-key: SonarCloud project key. (default: '')
 215     :sonarcloud-project-organization: SonarCloud project organization.
 216         (default: '')
 217     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 218     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 219     :stream: Keyword used to represent a release code-name.
 220         Often the same as the branch. (default: master)
 221     :submodule-recursive: Whether to checkout submodules recursively.
 222         (default: true)
 223     :submodule-timeout: Timeout (in minutes) for checkout operation.
 224         (default: 10)
 225     :submodule-disable: Disable submodule checkout operation.
 226         (default: false)
 227     :tox-dir: Directory containing the project's tox.ini relative to
 228         the workspace. The default uses tox.ini at the project root.
 229         (default: '.')
 230     :tox-envs: Tox environments to run. If blank run everything described
 231         in tox.ini. (default: '')
 232     :gerrit_sonar_triggers: Override Gerrit Triggers.
 233     :gerrit_trigger_file_paths: Override file paths used to filter which file
 234         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 235         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 236
 237 .. comment Stop ignoring
 238
 239
 240 Tox SonarQube
 241 -------------
 242
 243 The SonarQube job invokes tox to run tests and generate code-coverage
 244 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
 245 code, gather coverage data, and upload the results to a SonarQube server
 246 such as SonarCloud.io. Optionally runs a shell script before tox.
 247
 248 Requires ``SonarQube Scanner for Jenkins``
 249
 250 This job runs on the master branch because the basic Sonar configuration
 251 does not support multi-branch.
 252
 253 Plug-in configurations
 254     Manage Jenkins --> Configure System --> SonarQube servers
 255         - Name: Sonar (fixed)
 256         - Server URL: https://sonar.project.org/ or https://sonarcloud.io
 257         - Server authentication token: none for local, API token (saved as
 258           a "secret text" credential) for Sonarcloud
 259
 260     Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
 261         - Name: SonarQube Scanner (fixed)
 262         - Install automatically
 263         - Select latest version
 264
 265 :Template Names:
 266
 267     - {project-name}-tox-sonarqube
 268     - gerrit-tox-sonarqube
 269     - github-tox-sonarqube
 270
 271 :Comment Trigger: ``run-sonar``
 272
 273 :Required parameters:
 274
 275     :build-node: The node to run the build on.
 276         (Commonly in defaults.yaml)
 277     :jenkins-ssh-credential: Credential to use for SSH.
 278         (Commonly in defaults.yaml)
 279     :project: The git repository name.
 280     :project-name: Prefix used to name jobs.
 281
 282 .. comment Start ignoring WriteGoodLintBear
 283
 284 :Optional Parameters:
 285
 286     :archive-artifacts: Pattern for files to archive to the logs server
 287         (default: '\*\*/\*.log')
 288     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 289     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 290     :cron: Cron schedule when to trigger the job. This parameter also
 291         supports multiline input via YAML pipe | character in cases where
 292         one may want to provide more than 1 cron timer.  (default: @weekly)
 293     :disable-job: Whether to disable the job (default: false)
 294     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 295     :github-url: URL for Github. (default: https://github.com)
 296     :parallel: Boolean indicator for tox to run tests in parallel or series.
 297         (default: false, in series)
 298         If true use tox with the options "--parallel auto" and "--parallel-live"
 299         to parallelize jobs in the envlist.
 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         If true use tox with the options "--parallel auto" and "--parallel-live"
 411         to parallelize jobs in the envlist.
 412     :python-version: Python version to invoke pip install of tox-pyenv
 413         (default: python2)
 414     :stream: Keyword representing a release code-name.
 415         Often the same as the branch. (default: master)
 416     :submodule-recursive: Whether to checkout submodules recursively.
 417         (default: true)
 418     :submodule-timeout: Timeout (in minutes) for checkout operation.
 419         (default: 10)
 420     :submodule-disable: Disable submodule checkout operation.
 421         (default: false)
 422     :tox-dir: Directory containing the project's tox.ini relative to
 423         the workspace. The default uses tox.ini at the project root.
 424         (default: '.')
 425     :tox-envs: Tox environments to run. If blank run everything described
 426         in tox.ini. (default: '')
 427     :gerrit_trigger_file_paths: Override file paths used to filter which file
 428         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 429         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 430
 431
 432 Tox Merge
 433 ---------
 434
 435 Tox runner to verify a project after merge of a patch set.  This job
 436 is pyenv aware so if the image contains an installation of pyenv at
 437 /opt/pyenv it will pick it up and run Python tests with the
 438 appropriate Python versions. This job will set the following pyenv
 439 variables before running.
 440
 441 .. code:: bash
 442
 443    export PYENV_ROOT="/opt/pyenv"
 444    export PATH="$PYENV_ROOT/bin:$PATH"
 445
 446 :Template Names:
 447
 448     - {project-name}-tox-merge-{stream}
 449     - gerrit-tox-merge
 450     - github-tox-merge
 451
 452 :Comment Trigger: **remerge** post a comment with the trigger to launch
 453     this job manually. Do not include any other text or vote in the
 454     same comment.
 455
 456 :Required Parameters:
 457
 458     :build-node: The node to run build on.
 459     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 460         in defaults.yaml)
 461
 462 :Optional Parameters:
 463
 464     :branch: The branch to build against. (default: master)
 465     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 466     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 467     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 468     :pre-build-script: Shell script to execute before the CLM builder.
 469         For example, install prerequisites or move files to the repo root.
 470         (default: a string with a shell comment)
 471     :python-version: Python version to invoke pip install of tox-pyenv
 472         (default: python2)
 473     :stream: Keyword representing a release code-name.
 474         Often the same as the branch. (default: master)
 475     :submodule-recursive: Whether to checkout submodules recursively.
 476         (default: true)
 477     :submodule-timeout: Timeout (in minutes) for checkout operation.
 478         (default: 10)
 479     :submodule-disable: Disable submodule checkout operation.
 480         (default: false)
 481     :tox-dir: Directory containing the project's tox.ini relative to
 482         the workspace. The default uses tox.ini at the project root.
 483         (default: '.')
 484     :tox-envs: Tox environments to run. If blank run everything described
 485         in tox.ini. (default: '')
 486     :gerrit_trigger_file_paths: Override file paths used to filter which file
 487         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 488         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 489
 490
 491 PyPI Merge
 492 ----------
 493
 494 Creates and uploads package distribution files on merge of a patch set.
 495 Runs tox, builds a source distribution and (optionally) a binary
 496 distribution, and uploads the distribution(s) to a PyPI repository.
 497 The project git repository must have a setup.py file
 498 with configuration for packaging the component.
 499
 500 Projects can choose **either** this template to publish on merge,
 501 **or** the Stage template to publish on command.
 502
 503 This job should use a staging repository like testpypi.python.org,
 504 which sets up use of release jobs to promote the distributions later.
 505 This job can also use a public release area like the global PyPI
 506 repository if the release process is not needed. These PyPI
 507 repositories allow upload of a package at a specific version once,
 508 they do not allow overwrite of a package.  This means that a merge job
 509 will fail in the upload step if the package version already exists in
 510 the target repository.
 511
 512 The tox runner is pyenv aware so if the image contains an installation
 513 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 514 the appropriate Python versions. The tox runner sets the following
 515 pyenv variables before running.
 516
 517 .. code:: bash
 518
 519    export PYENV_ROOT="/opt/pyenv"
 520    export PATH="$PYENV_ROOT/bin:$PATH"
 521
 522 See the recommended directory layout documented in the PyPI Verify job.
 523
 524 Jobs using this PyPI template depend on a .pypirc configuration file
 525 in the Jenkins builder home directory. An example appears next that uses
 526 API tokens. Note that in the [pypi] entry the repository key-value pair
 527 is optional, it defaults to pypi.org.
 528
 529 .. code-block:: bash
 530
 531     [distutils] # this tells distutils what package indexes you can push to
 532     index-servers = pypi-test pypi
 533
 534     [pypi-test]
 535     repository: https://test.pypi.org/legacy/
 536     username: __token__
 537     password: pypi-test-api-token-goes-here
 538
 539     [pypi]
 540     username: __token__
 541     password: pypi-api-token-goes-here
 542
 543
 544 :Template Names:
 545
 546     - {project-name}-pypi-merge-{stream}
 547     - gerrit-pypi-merge
 548     - github-pypi-merge
 549
 550 :Comment Trigger: **remerge** post a comment with the trigger to launch
 551     this job manually. Do not include any other text or vote in the
 552     same comment.
 553
 554 :Required Parameters:
 555
 556     :build-node: The node to run the build on.
 557     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 558         in defaults.yaml)
 559     :mvn-settings: The settings file with credentials for the project
 560     :project: Git repository name
 561     :project-name: Jenkins job name prefix
 562
 563 :Optional Parameters:
 564
 565     :branch: The branch to build against. (default: master)
 566     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 567     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 568     :cron: Cron schedule when to trigger the job. Supports regular builds.
 569         Not useful when publishing to pypi.org because that rejects a package
 570         if the version exists. (default: empty)
 571     :disable-job: Whether to disable the job (default: false)
 572     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 573     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 574     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 575     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 576     :mvn-version: Version of maven to use. (default: mvn35)
 577     :parallel: Boolean indicator for tox to run tests in parallel or series.
 578         (default: false, in series)
 579         If true use tox with the options "--parallel auto" and "--parallel-live"
 580         to parallelize jobs in the envlist.
 581     :pre-build-script: Shell script to execute before the tox builder. For
 582         example, install system prerequisites. (default: a shell comment)
 583     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 584         ideally a server like test.pypi.org. (default: pypi-test)
 585     :python-version: Python version to invoke pip install of tox-pyenv
 586         (default: python3)
 587     :stream: Keyword representing a release code-name.
 588         Often the same as the branch. (default: master)
 589     :submodule-recursive: Whether to checkout submodules recursively.
 590         (default: true)
 591     :submodule-timeout: Timeout (in minutes) for checkout operation.
 592         (default: 10)
 593     :submodule-disable: Disable submodule checkout operation.
 594         (default: false)
 595     :tox-dir: Directory containing the project's tox.ini relative to
 596         the workspace. The default uses tox.ini at the project root.
 597         (default: '.')
 598     :tox-envs: Tox environments to run. If blank run everything described
 599         in tox.ini. (default: '')
 600     :gerrit_trigger_file_paths: Override file paths used to filter which file
 601         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 602         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 603
 604
 605 PyPI Stage
 606 ----------
 607
 608 Creates and uploads package distribution files on receipt of a comment.
 609 Runs tox, builds a source distribution and (optionally) a binary
 610 distribution, and uploads the distribution(s) to a PyPI repository.
 611 The project git repository must have a setup.py file with configuration
 612 for packaging the component.
 613
 614 Projects can choose **either** this template to publish on command,
 615 **or** the Merge template to publish on merge.
 616
 617 This job should use a staging repository like testpypi.python.org,
 618 which sets up use of release jobs to promote the distributions later.
 619 This job can also use a public release area like the global PyPI
 620 repository if the release process is not needed. These PyPI
 621 repositories allow upload of a package at a specific version once,
 622 they do not allow overwrite of a package.  This means that a job
 623 will fail in the upload step if the package version already exists in
 624 the target repository.
 625
 626 The tox runner is pyenv aware so if the image contains an installation
 627 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 628 the appropriate Python versions. The tox runner sets the following
 629 pyenv variables before running.
 630
 631 .. code:: bash
 632
 633    export PYENV_ROOT="/opt/pyenv"
 634    export PATH="$PYENV_ROOT/bin:$PATH"
 635
 636 See the recommended directory layout documented in the PyPI Verify job.
 637
 638 Jobs using this PyPI template depend on a .pypirc configuration file
 639 in the Jenkins builder home directory. An example appears next that uses
 640 API tokens. Note that in the [pypi] entry the repository key-value pair
 641 is optional, it defaults to pypi.org.
 642
 643 .. code-block:: bash
 644
 645     [distutils] # this tells distutils what package indexes you can push to
 646     index-servers = pypi-test pypi
 647
 648     [pypi-test]
 649     repository: https://test.pypi.org/legacy/
 650     username: __token__
 651     password: pypi-test-api-token-goes-here
 652
 653     [pypi]
 654     username: __token__
 655     password: pypi-api-token-goes-here
 656
 657
 658 :Template Names:
 659
 660     - {project-name}-pypi-stage-{stream}
 661     - gerrit-pypi-stage
 662     - github-pypi-stage
 663
 664 :Comment Trigger: **stage-release** post a comment with the trigger to launch
 665     this job manually. Do not include any other text or vote in the
 666     same comment.
 667
 668 :Required Parameters:
 669
 670     :build-node: The node to run the build on.
 671     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 672         in defaults.yaml)
 673     :mvn-settings: The settings file with credentials for the project
 674     :project: Git repository name
 675     :project-name: Jenkins job name prefix
 676
 677 :Optional Parameters:
 678
 679     :branch: The branch to build against. (default: master)
 680     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 681     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 682     :cron: Cron schedule when to trigger the job. Supports regular builds.
 683         Not useful when publishing to pypi.org because that rejects a package
 684         if the version exists. (default: empty)
 685     :disable-job: Whether to disable the job (default: false)
 686     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 687     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 688     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 689     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 690     :mvn-version: Version of maven to use. (default: mvn35)
 691     :parallel: Boolean indicator for tox to run tests in parallel or series.
 692         (default: false, in series)
 693         If true use tox with the options "--parallel auto" and "--parallel-live"
 694         to parallelize jobs in the envlist.
 695     :pre-build-script: Shell script to execute before the tox builder. For
 696         example, install system prerequisites. (default: a shell comment)
 697     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 698         ideally a server like test.pypi.org. (default: pypi-test)
 699     :python-version: Python version to invoke pip install of tox-pyenv
 700         (default: python3)
 701     :stream: Keyword representing a release code-name.
 702         Often the same as the branch. (default: master)
 703     :submodule-recursive: Whether to checkout submodules recursively.
 704         (default: true)
 705     :submodule-timeout: Timeout (in minutes) for checkout operation.
 706         (default: 10)
 707     :submodule-disable: Disable submodule checkout operation.
 708         (default: false)
 709     :tox-dir: Directory containing the project's tox.ini relative to
 710         the workspace. The default uses tox.ini at the project root.
 711         (default: '.')
 712     :tox-envs: Tox environments to run. If blank run everything described
 713         in tox.ini. (default: '')
 714     :gerrit_trigger_file_paths: Override file paths used to filter which file
 715         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 716         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 717
 718 PyPI Verify
 719 -----------
 720
 721 Verifies a Python library project on creation of a patch set. Runs tox
 722 then builds a source distribution and (optionally) a binary
 723 distribution. The project repository must have a setup.py file with
 724 configuration for packaging the component.
 725
 726 Installable package projects should use the directory layout shown
 727 below. All Python files are in a repo subdirectory separate from
 728 non-Python files like documentation. This layout allows highly
 729 specific build-job triggers in Jenkins using the subdirectory
 730 paths. For example, a PyPI publisher job should not run on a non-Python
 731 file change such as documentation, because the job cannot upload the
 732 same package twice.
 733
 734 To make the document files available for building a Python package
 735 long description in setup.py, add a symbolic link "docs" in the
 736 package subdirectory pointing to the top-level docs directory.
 737
 738 .. code-block:: bash
 739
 740     git-repo-name/
 741     │
 742     ├── docs/
 743     │   ├── index.rst
 744     │   └── release-notes.rst
 745     │
 746     ├── helloworld-package/
 747     │   │
 748     │   └── helloworld/
 749     │   │   ├── __init__.py
 750     │   │   ├── helloworld.py
 751     │   │   └── helpers.py
 752     │   │
 753     │   ├── tests/
 754     │   │   ├── helloworld_tests.py
 755     │   │   └── helloworld_mocks.py
 756     │   │
 757     │   ├── requirements.txt
 758     │   └── setup.py
 759     │   └── tox.ini
 760     │
 761     ├── releases/
 762     │   └── pypi-helloworld.yaml
 763     │
 764     ├── .gitignore
 765     ├── LICENSE
 766     └── README.md
 767
 768
 769 The tox runner is pyenv aware so if the image contains an installation
 770 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 771 the appropriate Python versions. The tox runner sets the following
 772 pyenv variables before running.
 773
 774 .. code:: bash
 775
 776    export PYENV_ROOT="/opt/pyenv"
 777    export PATH="$PYENV_ROOT/bin:$PATH"
 778
 779 :Template Names:
 780
 781     - {project-name}-pypi-verify-{stream}
 782     - gerrit-pypi-verify
 783     - github-pypi-verify
 784
 785 :Comment Trigger: **recheck|reverify** post a comment with one of the
 786     triggers to launch this job manually. Do not include any other
 787     text or vote in the same comment.
 788
 789 :Required Parameters:
 790
 791     :build-node: The node to run the build on.
 792     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 793         in defaults.yaml)
 794     :mvn-settings: The settings file with credentials for the project
 795     :project: Git repository name
 796     :project-name: Jenkins job name prefix
 797
 798 :Optional Parameters:
 799
 800     :branch: The branch to build against. (default: master)
 801     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 802     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 803     :disable-job: Whether to disable the job (default: false)
 804     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 805     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 806     :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
 807     :mvn-params: Parameters to pass to the mvn CLI. (default: '')
 808     :mvn-version: Version of maven to use. (default: mvn35)
 809     :parallel: Boolean indicator for tox to run tests in parallel or series.
 810         (default: false, in series)
 811         If true use tox with the options "--parallel auto" and "--parallel-live"
 812         to parallelize jobs in the envlist.
 813     :pre-build-script: Shell script to execute before the tox builder. For
 814         example, install system prerequisites. (default: a shell comment)
 815     :python-version: Python version to invoke pip install of tox-pyenv
 816         (default: python3)
 817     :stream: Keyword representing a release code-name.
 818         Often the same as the branch. (default: master)
 819     :submodule-recursive: Whether to checkout submodules recursively.
 820         (default: true)
 821     :submodule-timeout: Timeout (in minutes) for checkout operation.
 822         (default: 10)
 823     :submodule-disable: Disable submodule checkout operation.
 824         (default: false)
 825     :tox-dir: Directory containing the project's tox.ini relative to
 826         the workspace. The default uses tox.ini at the project root.
 827         (default: '.')
 828     :tox-envs: Tox environments to run. If blank run everything described
 829         in tox.ini. (default: '')
 830     :gerrit_trigger_file_paths: Override file paths used to filter which file
 831         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 832         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit