8 .. include:: ../job-groups.rst
10 Below is a list of Python job groups:
12 .. literalinclude:: ../../jjb/lf-python-job-groups.yaml
19 lf-infra-nexus-iq-python-cli
20 ----------------------------
22 Runs Nexus IQ command-line interface CLM scan on Python package requirements.
26 :nexus-iq-project-name: Project name in Nexus IQ to send results to.
27 :requirements-file: File name with output of pip freeze.
32 Installs Tox into a virtualenv.
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".
42 Creates a Tox virtual environment and invokes tox.
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".
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:
69 # use pip to report dependencies with versions
70 whitelist_externals = sh
71 commands = sh -c 'pip freeze > requirements.txt'
74 This job runs on the master branch because the basic Nexus IQ configuration
75 does not support multi-branch.
79 - {project-name}-tox-nexus-iq-clm
80 - gerrit-tox-nexus-iq-clm
81 - github-tox-nexus-iq-clm
83 :Comment Trigger: ``run-clm``
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.
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
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
121 :requirements-file: Name of file with output of pip freeze.
122 (default: requirements.txt)
123 :submodule-recursive: Whether to checkout submodules recursively.
125 :submodule-timeout: Timeout (in minutes) for checkout operation.
127 :submodule-disable: Disable submodule checkout operation.
129 :tox-dir: Directory containing the project's tox.ini relative to
130 the workspace. The default uses tox.ini at the project root.
132 :tox-envs: Tox environment with the appropriate pip freeze invocation.
135 Python Sonar with CLI
136 ---------------------
138 Sonar scans for non Maven based repos. This job downloads the CLI
139 and runs a scan to publish the report to SonarCloud.
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
145 For more details refer to sonar documentation:
147 https://docs.sonarcloud.io/advanced-setup/ci-based-analysis/sonarscanner-cli/
151 - {project-name}-cli-sonar
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
159 :Required parameters:
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.
166 .. comment Start ignoring WriteGoodLintBear
168 :Optional parameters:
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 * * *
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
195 :sonarcloud-project-key: SonarCloud project key. (default: '')
196 :sonarcloud-project-organization: SonarCloud project organization.
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.
209 :submodule-timeout: Timeout (in minutes) for checkout operation.
211 :submodule-disable: Disable submodule checkout operation.
213 :tox-dir: Directory containing the project's tox.ini relative to
214 the workspace. The default uses tox.ini at the project root.
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
223 .. comment Stop ignoring
225 Python Sonar with Tox
226 ---------------------
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.
232 **Deprecated**, new projects should use Tox Sonarqube.
234 To get the Sonar coverage results, file tox.ini must exist and contain
235 coverage commands to run.
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.
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.
252 coverage run --module pytest --junitxml xunit-results.xml
253 coverage xml --omit=".tox/py3/*","tests/*"
254 coverage report --omit=".tox/py3/*","tests/*"
256 For more details refer to coverage and sonar documentation:
258 https://coverage.readthedocs.io/
260 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
264 - {project-name}-tox-sonar
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
272 :Required parameters:
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.
279 .. comment Start ignoring WriteGoodLintBear
281 :Optional parameters:
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 * * *
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
308 :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
310 :sonarcloud-project-key: SonarCloud project key. (default: '')
311 :sonarcloud-project-organization: SonarCloud project organization.
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.
321 :submodule-timeout: Timeout (in minutes) for checkout operation.
323 :submodule-disable: Disable submodule checkout operation.
325 :tox-dir: Directory containing the project's tox.ini relative to
326 the workspace. The default uses tox.ini at the project root.
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
335 .. comment Stop ignoring
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.
346 Requires ``SonarQube Scanner for Jenkins``
348 This job runs on the master branch because the basic Sonar configuration
349 does not support multi-branch.
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
358 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
359 - Name: SonarQube Scanner (fixed)
360 - Install automatically
361 - Select latest version
365 - {project-name}-tox-sonarqube
366 - gerrit-tox-sonarqube
367 - github-tox-sonarqube
369 :Comment Trigger: ``run-sonar``
371 :Required parameters:
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.
380 .. comment Start ignoring WriteGoodLintBear
382 :Optional Parameters:
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
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.
414 :tox-envs: Tox environments to run. If blank run everything described
415 in tox.ini. (default: '')
417 .. comment Stop ignoring
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``.
425 :Required Sonar Properties:
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".
436 :Optional Sonar Properties:
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/
443 Example job definition
444 ^^^^^^^^^^^^^^^^^^^^^^
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.
452 name: my-package-sonar
454 project-name: my-package
455 sonar-project-file: ""
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
466 - gerrit-tox-sonarqube
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.
480 export PYENV_ROOT="/opt/pyenv"
481 export PATH="$PYENV_ROOT/bin:$PATH"
485 - {project-name}-tox-verify-{stream}
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.
493 :Required Parameters:
495 :build-node: The node to run build on.
496 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
499 :Optional Parameters:
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
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.
520 :submodule-timeout: Timeout (in minutes) for checkout operation.
522 :submodule-disable: Disable submodule checkout operation.
524 :tox-dir: Directory containing the project's tox.ini relative to
525 the workspace. The default uses tox.ini at the project root.
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
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.
545 export PYENV_ROOT="/opt/pyenv"
546 export PATH="$PYENV_ROOT/bin:$PATH"
550 - {project-name}-tox-merge-{stream}
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
558 :Required Parameters:
560 :build-node: The node to run build on.
561 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
564 :Optional Parameters:
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
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.
579 :submodule-timeout: Timeout (in minutes) for checkout operation.
581 :submodule-disable: Disable submodule checkout operation.
583 :tox-dir: Directory containing the project's tox.ini relative to
584 the workspace. The default uses tox.ini at the project root.
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
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.
602 Projects can choose **either** this template to publish on merge,
603 **or** the Stage template to publish on command.
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.
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.
621 export PYENV_ROOT="/opt/pyenv"
622 export PATH="$PYENV_ROOT/bin:$PATH"
624 See the recommended directory layout documented in the PyPI Verify job.
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.
633 [distutils] # this tells distutils what package indexes you can push to
634 index-servers = pypi-test pypi
637 repository: https://test.pypi.org/legacy/
639 password: pypi-test-api-token-goes-here
643 password: pypi-api-token-goes-here
648 - {project-name}-pypi-merge-{stream}
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
656 :Required Parameters:
658 :build-node: The node to run the build on.
659 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
661 :mvn-settings: The settings file with credentials for the project
662 :project: Git repository name
663 :project-name: Jenkins job name prefix
665 :Optional Parameters:
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
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.
695 :submodule-timeout: Timeout (in minutes) for checkout operation.
697 :submodule-disable: Disable submodule checkout operation.
699 :tox-dir: Directory containing the project's tox.ini relative to
700 the workspace. The default uses tox.ini at the project root.
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
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.
718 Projects can choose **either** this template to publish on command,
719 **or** the Merge template to publish on merge.
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.
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.
737 export PYENV_ROOT="/opt/pyenv"
738 export PATH="$PYENV_ROOT/bin:$PATH"
740 See the recommended directory layout documented in the PyPI Verify job.
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.
749 [distutils] # this tells distutils what package indexes you can push to
750 index-servers = pypi-test pypi
753 repository: https://test.pypi.org/legacy/
755 password: pypi-test-api-token-goes-here
759 password: pypi-api-token-goes-here
764 - {project-name}-pypi-stage-{stream}
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
772 :Required Parameters:
774 :build-node: The node to run the build on.
775 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
777 :mvn-settings: The settings file with credentials for the project
778 :project: Git repository name
779 :project-name: Jenkins job name prefix
781 :Optional Parameters:
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
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.
811 :submodule-timeout: Timeout (in minutes) for checkout operation.
813 :submodule-disable: Disable submodule checkout operation.
815 :tox-dir: Directory containing the project's tox.ini relative to
816 the workspace. The default uses tox.ini at the project root.
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
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.
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
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.
850 │ └── release-notes.rst
852 ├── helloworld-package/
856 │ │ ├── helloworld.py
860 │ │ ├── helloworld_tests.py
861 │ │ └── helloworld_mocks.py
863 │ ├── requirements.txt
868 │ └── pypi-helloworld.yaml
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.
882 export PYENV_ROOT="/opt/pyenv"
883 export PATH="$PYENV_ROOT/bin:$PATH"
887 - {project-name}-pypi-verify-{stream}
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.
895 :Required Parameters:
897 :build-node: The node to run the build on.
898 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
900 :mvn-settings: The settings file with credentials for the project
901 :project: Git repository name
902 :project-name: Jenkins job name prefix
904 :Optional Parameters:
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
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.
929 :submodule-timeout: Timeout (in minutes) for checkout operation.
931 :submodule-disable: Disable submodule checkout operation.
933 :tox-dir: Directory containing the project's tox.ini relative to
934 the workspace. The default uses tox.ini at the project root.
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