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 :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
119 :requirements-file: Name of file with output of pip freeze.
120 (default: requirements.txt)
121 :submodule-recursive: Whether to checkout submodules recursively.
123 :submodule-timeout: Timeout (in minutes) for checkout operation.
125 :submodule-disable: Disable submodule checkout operation.
127 :tox-dir: Directory containing the project's tox.ini relative to
128 the workspace. The default uses tox.ini at the project root.
130 :tox-envs: Tox environment with the appropriate pip freeze invocation.
133 Python Sonar with CLI
134 ---------------------
136 Sonar scans for non Maven based repos. This job downloads the CLI
137 and runs a scan to publish the report to SonarCloud.
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
143 For more details refer to sonar documentation:
145 https://docs.sonarcloud.io/advanced-setup/ci-based-analysis/sonarscanner-cli/
149 - {project-name}-cli-sonar
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
157 :Required parameters:
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.
164 .. comment Start ignoring WriteGoodLintBear
166 :Optional parameters:
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 * * *
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
193 :sonarcloud-project-key: SonarCloud project key. (default: '')
194 :sonarcloud-project-organization: SonarCloud project organization.
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.
205 :submodule-timeout: Timeout (in minutes) for checkout operation.
207 :submodule-disable: Disable submodule checkout operation.
209 :tox-dir: Directory containing the project's tox.ini relative to
210 the workspace. The default uses tox.ini at the project root.
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
219 .. comment Stop ignoring
221 Python Sonar with Tox
222 ---------------------
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.
228 **Deprecated**, new projects should use Tox Sonarqube.
230 To get the Sonar coverage results, file tox.ini must exist and contain
231 coverage commands to run.
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.
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.
248 coverage run --module pytest --junitxml xunit-results.xml
249 coverage xml --omit=".tox/py3/*","tests/*"
250 coverage report --omit=".tox/py3/*","tests/*"
252 For more details refer to coverage and sonar documentation:
254 https://coverage.readthedocs.io/
256 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
260 - {project-name}-tox-sonar
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
268 :Required parameters:
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.
275 .. comment Start ignoring WriteGoodLintBear
277 :Optional parameters:
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 * * *
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
304 :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
306 :sonarcloud-project-key: SonarCloud project key. (default: '')
307 :sonarcloud-project-organization: SonarCloud project organization.
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.
315 :submodule-timeout: Timeout (in minutes) for checkout operation.
317 :submodule-disable: Disable submodule checkout operation.
319 :tox-dir: Directory containing the project's tox.ini relative to
320 the workspace. The default uses tox.ini at the project root.
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
329 .. comment Stop ignoring
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.
340 Requires ``SonarQube Scanner for Jenkins``
342 This job runs on the master branch because the basic Sonar configuration
343 does not support multi-branch.
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
352 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
353 - Name: SonarQube Scanner (fixed)
354 - Install automatically
355 - Select latest version
359 - {project-name}-tox-sonarqube
360 - gerrit-tox-sonarqube
361 - github-tox-sonarqube
363 :Comment Trigger: ``run-sonar``
365 :Required parameters:
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.
374 .. comment Start ignoring WriteGoodLintBear
376 :Optional Parameters:
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
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.
408 :tox-envs: Tox environments to run. If blank run everything described
409 in tox.ini. (default: '')
411 .. comment Stop ignoring
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``.
419 :Required Sonar Properties:
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".
430 :Optional Sonar Properties:
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/
437 Example job definition
438 ^^^^^^^^^^^^^^^^^^^^^^
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.
446 name: my-package-sonar
448 project-name: my-package
449 sonar-project-file: ""
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
460 - gerrit-tox-sonarqube
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.
474 export PYENV_ROOT="/opt/pyenv"
475 export PATH="$PYENV_ROOT/bin:$PATH"
479 - {project-name}-tox-verify-{stream}
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.
487 :Required Parameters:
489 :build-node: The node to run build on.
490 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
493 :Optional Parameters:
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
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.
514 :submodule-timeout: Timeout (in minutes) for checkout operation.
516 :submodule-disable: Disable submodule checkout operation.
518 :tox-dir: Directory containing the project's tox.ini relative to
519 the workspace. The default uses tox.ini at the project root.
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
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.
539 export PYENV_ROOT="/opt/pyenv"
540 export PATH="$PYENV_ROOT/bin:$PATH"
544 - {project-name}-tox-merge-{stream}
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
552 :Required Parameters:
554 :build-node: The node to run build on.
555 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
558 :Optional Parameters:
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
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.
573 :submodule-timeout: Timeout (in minutes) for checkout operation.
575 :submodule-disable: Disable submodule checkout operation.
577 :tox-dir: Directory containing the project's tox.ini relative to
578 the workspace. The default uses tox.ini at the project root.
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
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.
596 Projects can choose **either** this template to publish on merge,
597 **or** the Stage template to publish on command.
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.
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.
615 export PYENV_ROOT="/opt/pyenv"
616 export PATH="$PYENV_ROOT/bin:$PATH"
618 See the recommended directory layout documented in the PyPI Verify job.
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.
627 [distutils] # this tells distutils what package indexes you can push to
628 index-servers = pypi-test pypi
631 repository: https://test.pypi.org/legacy/
633 password: pypi-test-api-token-goes-here
637 password: pypi-api-token-goes-here
642 - {project-name}-pypi-merge-{stream}
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
650 :Required Parameters:
652 :build-node: The node to run the build on.
653 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
655 :mvn-settings: The settings file with credentials for the project
656 :project: Git repository name
657 :project-name: Jenkins job name prefix
659 :Optional Parameters:
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
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.
689 :submodule-timeout: Timeout (in minutes) for checkout operation.
691 :submodule-disable: Disable submodule checkout operation.
693 :tox-dir: Directory containing the project's tox.ini relative to
694 the workspace. The default uses tox.ini at the project root.
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
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.
712 Projects can choose **either** this template to publish on command,
713 **or** the Merge template to publish on merge.
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.
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.
731 export PYENV_ROOT="/opt/pyenv"
732 export PATH="$PYENV_ROOT/bin:$PATH"
734 See the recommended directory layout documented in the PyPI Verify job.
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.
743 [distutils] # this tells distutils what package indexes you can push to
744 index-servers = pypi-test pypi
747 repository: https://test.pypi.org/legacy/
749 password: pypi-test-api-token-goes-here
753 password: pypi-api-token-goes-here
758 - {project-name}-pypi-stage-{stream}
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
766 :Required Parameters:
768 :build-node: The node to run the build on.
769 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
771 :mvn-settings: The settings file with credentials for the project
772 :project: Git repository name
773 :project-name: Jenkins job name prefix
775 :Optional Parameters:
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
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.
805 :submodule-timeout: Timeout (in minutes) for checkout operation.
807 :submodule-disable: Disable submodule checkout operation.
809 :tox-dir: Directory containing the project's tox.ini relative to
810 the workspace. The default uses tox.ini at the project root.
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
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.
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
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.
844 │ └── release-notes.rst
846 ├── helloworld-package/
850 │ │ ├── helloworld.py
854 │ │ ├── helloworld_tests.py
855 │ │ └── helloworld_mocks.py
857 │ ├── requirements.txt
862 │ └── pypi-helloworld.yaml
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.
876 export PYENV_ROOT="/opt/pyenv"
877 export PATH="$PYENV_ROOT/bin:$PATH"
881 - {project-name}-pypi-verify-{stream}
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.
889 :Required Parameters:
891 :build-node: The node to run the build on.
892 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
894 :mvn-settings: The settings file with credentials for the project
895 :project: Git repository name
896 :project-name: Jenkins job name prefix
898 :Optional Parameters:
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
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.
923 :submodule-timeout: Timeout (in minutes) for checkout operation.
925 :submodule-disable: Disable submodule checkout operation.
927 :tox-dir: Directory containing the project's tox.ini relative to
928 the workspace. The default uses tox.ini at the project root.
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