docs/jjb/lf-python-jobs.rst

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