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