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: SonarCloud API Token. (default: '')
199 :sonar-scanner-home: Sonar scanner home directory.
200 (default: $WORKSPACE/.sonar/sonar-scanner-$SONAR_SCANNER_VERSION-linux)
201 :sonar-scanner-opts: Sonar scanner Java options. (default: '-server')
202 :sonar-scanner-version: Version of sonar scanner to use. (default: 4.7.0.2747)
203 :stream: Keyword used to represent a release code-name.
204 Often the same as the branch. (default: master)
205 :submodule-recursive: Whether to checkout submodules recursively.
207 :submodule-timeout: Timeout (in minutes) for checkout operation.
209 :submodule-disable: Disable submodule checkout operation.
211 :tox-dir: Directory containing the project's tox.ini relative to
212 the workspace. The default uses tox.ini at the project root.
214 :tox-envs: Tox environments to run. If blank run everything described
215 in tox.ini. (default: '')
216 :gerrit_sonar_triggers: Override Gerrit Triggers.
217 :gerrit_trigger_file_paths: Override file paths used to filter which file
218 modifications trigger a build. Refer to JJB documentation for "file-path" details.
219 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
221 .. comment Stop ignoring
223 Python Sonar with Tox
224 ---------------------
226 Sonar scans for Python based repos. This job invokes tox to run tests
227 and gather coverage statistics from the test results, then invokes
228 Maven to publish the results to either a Sonar server or SonarCloud.
230 **Deprecated**, new projects should use Tox Sonarqube.
232 To get the Sonar coverage results, file tox.ini must exist and contain
233 coverage commands to run.
235 The coverage commands define the code that gets executed by the test
236 suites. Checking coverage does not guarantee that the tests execute
237 properly, but it identifies code that is not executed by any test.
239 This job reuses the Sonar builders used for Java/Maven projects which
240 run maven twice. The first invocation does nothing for Python
241 projects, so the job uses the goal ``validate`` by default. The second
242 invocation publishes results using the goal ``sonar:sonar`` by default.
250 coverage run --module pytest --junitxml xunit-results.xml
251 coverage xml --omit=".tox/py3/*","tests/*"
252 coverage report --omit=".tox/py3/*","tests/*"
254 For more details refer to coverage and sonar documentation:
256 https://coverage.readthedocs.io/
258 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
262 - {project-name}-tox-sonar
266 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
267 this job manually. Do not include any other text or vote in the
270 :Required parameters:
272 :build-node: The node to run build on.
273 :jenkins-ssh-credential: Credential to use for SSH. (Generally should
274 get configured in defaults.yaml)
275 :mvn-settings: The name of the settings file with credentials for the project.
277 .. comment Start ignoring WriteGoodLintBear
279 :Optional parameters:
281 :branch: Git branch, should be master (default: master)
282 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
283 :build-timeout: Timeout in minutes before aborting build. (default: 60)
284 :cron: Cron schedule when to trigger the job. This parameter also
285 supports multiline input via YAML pipe | character in cases where
286 one may want to provide more than 1 cron timer. (default: H 11 * * *
288 :disable-job: Whether to disable the job (default: false)
289 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
290 :github-url: URL for Github. (default: https://github.com)
291 :java-version: Version of Java to use for the build. (default: openjdk11)
292 :mvn-global-settings: The name of the Maven global settings to use
293 :mvn-goals: The Maven goal to run first. (default: validate)
294 :mvn-version: Version of maven to use. (default: mvn35)
295 :parallel: If different from false, try pass this parameter to tox option
296 "--parallel" to parallelize jobs in the envlist (and then activate the
297 option "--parallel-live" to display output in logs).
298 Possible values are "auto" (equivalent to "true" for legacy),
299 "all" or any integer. Any other value is equivalent to "false".
300 (default: false, in series)
301 :pre-build-script: Shell script to execute before the Sonar builder.
302 For example, install prerequisites or move files to the repo root.
303 (default: a string with a shell comment)
304 :python-version: Python version to invoke pip install of tox-pyenv
306 :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
308 :sonarcloud-project-key: SonarCloud project key. (default: '')
309 :sonarcloud-project-organization: SonarCloud project organization.
311 :sonarcloud-api-token: SonarCloud API Token. (default: '')
312 :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
313 :stream: Keyword used to represent a release code-name.
314 Often the same as the branch. (default: master)
315 :submodule-recursive: Whether to checkout submodules recursively.
317 :submodule-timeout: Timeout (in minutes) for checkout operation.
319 :submodule-disable: Disable submodule checkout operation.
321 :tox-dir: Directory containing the project's tox.ini relative to
322 the workspace. The default uses tox.ini at the project root.
324 :tox-envs: Tox environments to run. If blank run everything described
325 in tox.ini. (default: '')
326 :gerrit_sonar_triggers: Override Gerrit Triggers.
327 :gerrit_trigger_file_paths: Override file paths used to filter which file
328 modifications trigger a build. Refer to JJB documentation for "file-path" details.
329 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
331 .. comment Stop ignoring
337 The SonarQube job invokes tox to run tests and generate code-coverage
338 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
339 code, gather coverage data, and upload the results to a SonarQube server
340 such as SonarCloud.io. Optionally runs a shell script before tox.
342 Requires ``SonarQube Scanner for Jenkins``
344 This job runs on the master branch because the basic Sonar configuration
345 does not support multi-branch.
347 Plug-in configurations
348 Manage Jenkins --> Configure System --> SonarQube servers
349 - Name: Sonar (fixed)
350 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
351 - Server authentication token: none for local, API token (saved as
352 a "secret text" credential) for Sonarcloud
354 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
355 - Name: SonarQube Scanner (fixed)
356 - Install automatically
357 - Select latest version
361 - {project-name}-tox-sonarqube
362 - gerrit-tox-sonarqube
363 - github-tox-sonarqube
365 :Comment Trigger: ``run-sonar``
367 :Required parameters:
369 :build-node: The node to run the build on.
370 (Commonly in defaults.yaml)
371 :jenkins-ssh-credential: Credential to use for SSH.
372 (Commonly in defaults.yaml)
373 :project: The git repository name.
374 :project-name: Prefix used to name jobs.
376 .. comment Start ignoring WriteGoodLintBear
378 :Optional Parameters:
380 :archive-artifacts: Pattern for files to archive to the logs server
381 (default: '\*\*/\*.log')
382 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
383 :build-timeout: Timeout in minutes before aborting build. (default: 15)
384 :cron: Cron schedule when to trigger the job. This parameter also
385 supports multiline input via YAML pipe | character in cases where
386 one may want to provide more than 1 cron timer. (default: @weekly)
387 :disable-job: Whether to disable the job (default: false)
388 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
389 :github-url: URL for Github. (default: https://github.com)
390 :parallel: If different from false, try pass this parameter to tox option
391 "--parallel" to parallelize jobs in the envlist (and then activate the
392 option "--parallel-live" to display output in logs).
393 Possible values are "auto" (equivalent to "true" for legacy),
394 "all" or any integer. Any other value is equivalent to "false".
395 (default: false, in series)
396 :pre-build-script: Shell script to run before tox. Useful for setting up
397 dependencies. (default: a string with a shell comment)
398 :python-version: Python version to invoke pip install of tox-pyenv
400 :sonar-additional-args: Command line arguments. (default: '')
401 :sonar-java-opts: JVM options. For example, use option -Xmx
402 to increase the memory size limit. (default: '')
403 :sonar-project-file: The file name with Sonar configuration properties
404 (default: sonar-project.properties)
405 :sonar-properties: Sonar configuration properties. (default: '')
406 :sonar-task: Sonar task to run. (default: '')
407 :tox-dir: Directory containing the project's tox.ini relative to
408 the workspace. The default uses tox.ini at the project root.
410 :tox-envs: Tox environments to run. If blank run everything described
411 in tox.ini. (default: '')
413 .. comment Stop ignoring
415 .. note:: A job definition must provide one of the optional parameters
416 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
417 empty. Set Sonar properties directly in the job definition by setting
418 the ``sonar-project-file`` property to ``""`` and adding all properties
419 under ``sonar-properties``.
421 :Required Sonar Properties:
423 - sonar.login: The API token for authentication at SonarCloud.
424 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
425 - sonar.organization: The umbrella project name; e.g., "opendaylight".
426 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
427 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
428 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
429 teams use the catenation of sonar.organization, an underscore, and
430 sonar.projectName; e.g., "opendaylight_infrautils".
432 :Optional Sonar Properties:
434 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
435 - Documentation of SonarQube properties is here:
436 https://docs.sonarqube.org/latest/analysis/overview/
439 Example job definition
440 ^^^^^^^^^^^^^^^^^^^^^^
442 The following example defines a job for a basic Python project. This definition
443 uses configuration parameters in the umbrella project's defaults.yaml file.
448 name: my-package-sonar
450 project-name: my-package
451 sonar-project-file: ""
453 sonar.login={sonarcloud_api_token}
454 sonar.projectKey={sonarcloud_project_organization}_{project-name}
455 sonar.projectName={project-name}
456 sonar.organization={sonarcloud_project_organization}
457 sonar.sourceEncoding=UTF-8
458 sonar.sources=mypackage
459 sonar.exclusions=tests/*,setup.py
460 sonar.python.coverage.reportPaths=coverage.xml
462 - gerrit-tox-sonarqube
468 Tox runner to verify a project on creation of a patch set. This job
469 is pyenv aware so if the image contains an installation of pyenv at
470 /opt/pyenv it will pick it up and run Python tests with the
471 appropriate Python versions. This job will set the following pyenv
472 variables before running.
476 export PYENV_ROOT="/opt/pyenv"
477 export PATH="$PYENV_ROOT/bin:$PATH"
481 - {project-name}-tox-verify-{stream}
485 :Comment Trigger: **recheck|reverify** post a comment with one of the
486 triggers to launch this job manually. Do not include any other
487 text or vote in the same comment.
489 :Required Parameters:
491 :build-node: The node to run build on.
492 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
495 :Optional Parameters:
497 :branch: The branch to build against. (default: master)
498 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
499 :build-timeout: Timeout in minutes before aborting build. (default: 10)
500 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
501 :pre-build-script: Shell script to execute before the Tox builder.
502 For example, install prerequisites or move files to the repo root.
503 (default: a string with a shell comment)
504 :parallel: If different from false, try pass this parameter to tox option
505 "--parallel" to parallelize jobs in the envlist (and then activate the
506 option "--parallel-live" to display output in logs).
507 Possible values are "auto" (equivalent to "true" for legacy),
508 "all" or any integer. Any other value is equivalent to "false".
509 (default: false, in series)
510 :python-version: Python version to invoke pip install of tox-pyenv
512 :stream: Keyword representing a release code-name.
513 Often the same as the branch. (default: master)
514 :submodule-recursive: Whether to checkout submodules recursively.
516 :submodule-timeout: Timeout (in minutes) for checkout operation.
518 :submodule-disable: Disable submodule checkout operation.
520 :tox-dir: Directory containing the project's tox.ini relative to
521 the workspace. The default uses tox.ini at the project root.
523 :tox-envs: Tox environments to run. If blank run everything described
524 in tox.ini. (default: '')
525 :gerrit_trigger_file_paths: Override file paths used to filter which file
526 modifications trigger a build. Refer to JJB documentation for "file-path" details.
527 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
533 Tox runner to verify a project after merge of a patch set. This job
534 is pyenv aware so if the image contains an installation of pyenv at
535 /opt/pyenv it will pick it up and run Python tests with the
536 appropriate Python versions. This job will set the following pyenv
537 variables before running.
541 export PYENV_ROOT="/opt/pyenv"
542 export PATH="$PYENV_ROOT/bin:$PATH"
546 - {project-name}-tox-merge-{stream}
550 :Comment Trigger: **remerge** post a comment with the trigger to launch
551 this job manually. Do not include any other text or vote in the
554 :Required Parameters:
556 :build-node: The node to run build on.
557 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
560 :Optional Parameters:
562 :branch: The branch to build against. (default: master)
563 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
564 :build-timeout: Timeout in minutes before aborting build. (default: 10)
565 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
566 :pre-build-script: Shell script to execute before the CLM builder.
567 For example, install prerequisites or move files to the repo root.
568 (default: a string with a shell comment)
569 :python-version: Python version to invoke pip install of tox-pyenv
571 :stream: Keyword representing a release code-name.
572 Often the same as the branch. (default: master)
573 :submodule-recursive: Whether to checkout submodules recursively.
575 :submodule-timeout: Timeout (in minutes) for checkout operation.
577 :submodule-disable: Disable submodule checkout operation.
579 :tox-dir: Directory containing the project's tox.ini relative to
580 the workspace. The default uses tox.ini at the project root.
582 :tox-envs: Tox environments to run. If blank run everything described
583 in tox.ini. (default: '')
584 :gerrit_trigger_file_paths: Override file paths used to filter which file
585 modifications trigger a build. Refer to JJB documentation for "file-path" details.
586 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
592 Creates and uploads package distribution files on merge of a patch set.
593 Runs tox, builds a source distribution and (optionally) a binary
594 distribution, and uploads the distribution(s) to a PyPI repository.
595 The project git repository must have a setup.py file
596 with configuration for packaging the component.
598 Projects can choose **either** this template to publish on merge,
599 **or** the Stage template to publish on command.
601 This job should use a staging repository like testpypi.python.org,
602 which sets up use of release jobs to promote the distributions later.
603 This job can also use a public release area like the global PyPI
604 repository if the release process is not needed. These PyPI
605 repositories allow upload of a package at a specific version once,
606 they do not allow overwrite of a package. This means that a merge job
607 will fail in the upload step if the package version already exists in
608 the target repository.
610 The tox runner is pyenv aware so if the image contains an installation
611 of pyenv at /opt/pyenv it will pick it up and run Python tests with
612 the appropriate Python versions. The tox runner sets the following
613 pyenv variables before running.
617 export PYENV_ROOT="/opt/pyenv"
618 export PATH="$PYENV_ROOT/bin:$PATH"
620 See the recommended directory layout documented in the PyPI Verify job.
622 Jobs using this PyPI template depend on a .pypirc configuration file
623 in the Jenkins builder home directory. An example appears next that uses
624 API tokens. Note that in the [pypi] entry the repository key-value pair
625 is optional, it defaults to pypi.org.
629 [distutils] # this tells distutils what package indexes you can push to
630 index-servers = pypi-test pypi
633 repository: https://test.pypi.org/legacy/
635 password: pypi-test-api-token-goes-here
639 password: pypi-api-token-goes-here
644 - {project-name}-pypi-merge-{stream}
648 :Comment Trigger: **remerge** post a comment with the trigger to launch
649 this job manually. Do not include any other text or vote in the
652 :Required Parameters:
654 :build-node: The node to run the build on.
655 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
657 :mvn-settings: The settings file with credentials for the project
658 :project: Git repository name
659 :project-name: Jenkins job name prefix
661 :Optional Parameters:
663 :branch: The branch to build against. (default: master)
664 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
665 :build-timeout: Timeout in minutes before aborting build. (default: 15)
666 :cron: Cron schedule when to trigger the job. Supports regular builds.
667 Not useful when publishing to pypi.org because that rejects a package
668 if the version exists. (default: empty)
669 :disable-job: Whether to disable the job (default: false)
670 :dist-binary: Whether to build a binary wheel distribution. (default: true)
671 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
672 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
673 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
674 :mvn-version: Version of maven to use. (default: mvn35)
675 :parallel: If different from false, try pass this parameter to tox option
676 "--parallel" to parallelize jobs in the envlist (and then activate the
677 option "--parallel-live" to display output in logs).
678 Possible values are "auto" (equivalent to "true" for legacy),
679 "all" or any integer. Any other value is equivalent to "false".
680 (default: false, in series)
681 :pre-build-script: Shell script to execute before the tox builder. For
682 example, install system prerequisites. (default: a shell comment)
683 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
684 ideally a server like test.pypi.org. (default: pypi-test)
685 :python-version: Python version to invoke pip install of tox-pyenv
687 :stream: Keyword representing a release code-name.
688 Often the same as the branch. (default: master)
689 :submodule-recursive: Whether to checkout submodules recursively.
691 :submodule-timeout: Timeout (in minutes) for checkout operation.
693 :submodule-disable: Disable submodule checkout operation.
695 :tox-dir: Directory containing the project's tox.ini relative to
696 the workspace. The default uses tox.ini at the project root.
698 :tox-envs: Tox environments to run. If blank run everything described
699 in tox.ini. (default: '')
700 :gerrit_trigger_file_paths: Override file paths used to filter which file
701 modifications trigger a build. Refer to JJB documentation for "file-path" details.
702 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
708 Creates and uploads package distribution files on receipt of a comment.
709 Runs tox, builds a source distribution and (optionally) a binary
710 distribution, and uploads the distribution(s) to a PyPI repository.
711 The project git repository must have a setup.py file with configuration
712 for packaging the component.
714 Projects can choose **either** this template to publish on command,
715 **or** the Merge template to publish on merge.
717 This job should use a staging repository like testpypi.python.org,
718 which sets up use of release jobs to promote the distributions later.
719 This job can also use a public release area like the global PyPI
720 repository if the release process is not needed. These PyPI
721 repositories allow upload of a package at a specific version once,
722 they do not allow overwrite of a package. This means that a job
723 will fail in the upload step if the package version already exists in
724 the target repository.
726 The tox runner is pyenv aware so if the image contains an installation
727 of pyenv at /opt/pyenv it will pick it up and run Python tests with
728 the appropriate Python versions. The tox runner sets the following
729 pyenv variables before running.
733 export PYENV_ROOT="/opt/pyenv"
734 export PATH="$PYENV_ROOT/bin:$PATH"
736 See the recommended directory layout documented in the PyPI Verify job.
738 Jobs using this PyPI template depend on a .pypirc configuration file
739 in the Jenkins builder home directory. An example appears next that uses
740 API tokens. Note that in the [pypi] entry the repository key-value pair
741 is optional, it defaults to pypi.org.
745 [distutils] # this tells distutils what package indexes you can push to
746 index-servers = pypi-test pypi
749 repository: https://test.pypi.org/legacy/
751 password: pypi-test-api-token-goes-here
755 password: pypi-api-token-goes-here
760 - {project-name}-pypi-stage-{stream}
764 :Comment Trigger: **stage-release** post a comment with the trigger to launch
765 this job manually. Do not include any other text or vote in the
768 :Required Parameters:
770 :build-node: The node to run the build on.
771 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
773 :mvn-settings: The settings file with credentials for the project
774 :project: Git repository name
775 :project-name: Jenkins job name prefix
777 :Optional Parameters:
779 :branch: The branch to build against. (default: master)
780 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
781 :build-timeout: Timeout in minutes before aborting build. (default: 15)
782 :cron: Cron schedule when to trigger the job. Supports regular builds.
783 Not useful when publishing to pypi.org because that rejects a package
784 if the version exists. (default: empty)
785 :disable-job: Whether to disable the job (default: false)
786 :dist-binary: Whether to build a binary wheel distribution. (default: true)
787 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
788 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
789 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
790 :mvn-version: Version of maven to use. (default: mvn35)
791 :parallel: If different from false, try pass this parameter to tox option
792 "--parallel" to parallelize jobs in the envlist (and then activate the
793 option "--parallel-live" to display output in logs).
794 Possible values are "auto" (equivalent to "true" for legacy),
795 "all" or any integer. Any other value is equivalent to "false".
796 (default: false, in series)
797 :pre-build-script: Shell script to execute before the tox builder. For
798 example, install system prerequisites. (default: a shell comment)
799 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
800 ideally a server like test.pypi.org. (default: pypi-test)
801 :python-version: Python version to invoke pip install of tox-pyenv
803 :stream: Keyword representing a release code-name.
804 Often the same as the branch. (default: master)
805 :submodule-recursive: Whether to checkout submodules recursively.
807 :submodule-timeout: Timeout (in minutes) for checkout operation.
809 :submodule-disable: Disable submodule checkout operation.
811 :tox-dir: Directory containing the project's tox.ini relative to
812 the workspace. The default uses tox.ini at the project root.
814 :tox-envs: Tox environments to run. If blank run everything described
815 in tox.ini. (default: '')
816 :gerrit_trigger_file_paths: Override file paths used to filter which file
817 modifications trigger a build. Refer to JJB documentation for "file-path" details.
818 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
823 Verifies a Python library project on creation of a patch set. Runs tox
824 then builds a source distribution and (optionally) a binary
825 distribution. The project repository must have a setup.py file with
826 configuration for packaging the component.
828 Installable package projects should use the directory layout shown
829 below. All Python files are in a repo subdirectory separate from
830 non-Python files like documentation. This layout allows highly
831 specific build-job triggers in Jenkins using the subdirectory
832 paths. For example, a PyPI publisher job should not run on a non-Python
833 file change such as documentation, because the job cannot upload the
836 To make the document files available for building a Python package
837 long description in setup.py, add a symbolic link "docs" in the
838 package subdirectory pointing to the top-level docs directory.
846 │ └── release-notes.rst
848 ├── helloworld-package/
852 │ │ ├── helloworld.py
856 │ │ ├── helloworld_tests.py
857 │ │ └── helloworld_mocks.py
859 │ ├── requirements.txt
864 │ └── pypi-helloworld.yaml
871 The tox runner is pyenv aware so if the image contains an installation
872 of pyenv at /opt/pyenv it will pick it up and run Python tests with
873 the appropriate Python versions. The tox runner sets the following
874 pyenv variables before running.
878 export PYENV_ROOT="/opt/pyenv"
879 export PATH="$PYENV_ROOT/bin:$PATH"
883 - {project-name}-pypi-verify-{stream}
887 :Comment Trigger: **recheck|reverify** post a comment with one of the
888 triggers to launch this job manually. Do not include any other
889 text or vote in the same comment.
891 :Required Parameters:
893 :build-node: The node to run the build on.
894 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
896 :mvn-settings: The settings file with credentials for the project
897 :project: Git repository name
898 :project-name: Jenkins job name prefix
900 :Optional Parameters:
902 :branch: The branch to build against. (default: master)
903 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
904 :build-timeout: Timeout in minutes before aborting build. (default: 15)
905 :disable-job: Whether to disable the job (default: false)
906 :dist-binary: Whether to build a binary wheel distribution. (default: true)
907 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
908 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
909 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
910 :mvn-version: Version of maven to use. (default: mvn35)
911 :parallel: If different from false, try pass this parameter to tox option
912 "--parallel" to parallelize jobs in the envlist (and then activate the
913 option "--parallel-live" to display output in logs).
914 Possible values are "auto" (equivalent to "true" for legacy),
915 "all" or any integer. Any other value is equivalent to "false".
916 (default: false, in series)
917 :pre-build-script: Shell script to execute before the tox builder. For
918 example, install system prerequisites. (default: a shell comment)
919 :python-version: Python version to invoke pip install of tox-pyenv
921 :stream: Keyword representing a release code-name.
922 Often the same as the branch. (default: master)
923 :submodule-recursive: Whether to checkout submodules recursively.
925 :submodule-timeout: Timeout (in minutes) for checkout operation.
927 :submodule-disable: Disable submodule checkout operation.
929 :tox-dir: Directory containing the project's tox.ini relative to
930 the workspace. The default uses tox.ini at the project root.
932 :tox-envs: Tox environments to run. If blank run everything described
933 in tox.ini. (default: '')
934 :gerrit_trigger_file_paths: Override file paths used to filter which file
935 modifications trigger a build. Refer to JJB documentation for "file-path" details.
936 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit