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