docs/jjb/lf-python-jobs.rst

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