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 for scanning 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.
138 Builds the code, downloads and runs a Snyk CLI scan of the code into the Snyk dashboard.
142 - {project-name}-python-snyk-cli-{stream}
143 - gerrit-python-snyk-cli
144 - github-python-snyk-cli
146 :Comment Trigger: run-snyk
148 :Required parameters:
150 :build-node: The node to run build on.
151 :jenkins-ssh-credential: Credential to use for SSH. (Generally configured in defaults.yaml)
152 :snyk-token-credential-id: Snyk API token to communicate with Jenkins.
153 :snyk-org-credential-id: Snyk organization ID.
155 :Optional parameters:
157 :branch: The branch to build against. (default: master)
158 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
159 :build-timeout: Timeout in minutes before aborting build. (default: 60)
160 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
161 :pre-build-script: Shell script to execute before the Tox builder.
162 For example, install prerequisites or move files to the repo root.
163 (default: a string with a shell comment)
164 :parallel: If different from false, try pass this parameter to tox option
165 "--parallel" to parallelize jobs in the envlist (and then activate the
166 option "--parallel-live" to display output in logs).
167 Possible values are "auto" (equivalent to "true" for legacy),
168 "all" or any integer. Any other value is equivalent to "false".
169 (default: false, in series)
170 :python-version: Python version to invoke pip install of tox-pyenv
172 :snyk-cli-options: Additional Snyk CLI options. (default: '')
173 :stream: Keyword representing a release code-name.
174 Often the same as the branch. (default: master)
175 :submodule-recursive: Whether to checkout submodules recursively.
177 :submodule-timeout: Timeout (in minutes) for checkout operation.
179 :submodule-disable: Disable submodule checkout operation.
181 :tox-dir: Directory containing the project's tox.ini relative to
182 the workspace. The default uses tox.ini at the project root.
184 :tox-envs: Tox environments to run. If blank run everything described
185 in tox.ini. (default: '')
186 :gerrit_trigger_file_paths: Override file paths used to filter which file
187 modifications trigger a build. Refer to JJB documentation for "file-path" details.
188 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
190 Python Sonar with CLI
191 ---------------------
193 Sonar scans for non Maven based repos. This job downloads the CLI
194 and runs a scan to publish the report to SonarCloud.
196 As suggested in SonarCoud's UI instructions, the job downloads and unzips
197 the Sonar SLI and executes a sonar-scanner command to process the
200 For more details refer to sonar documentation:
202 https://docs.sonarcloud.io/advanced-setup/ci-based-analysis/sonarscanner-cli/
206 - {project-name}-cli-sonar
210 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
211 this job manually. Do not include any other text or vote in the
214 :Required parameters:
216 :build-node: The node to run build on.
217 :jenkins-ssh-credential: Credential to use for SSH. (Generally should
218 get configured in defaults.yaml)
219 :mvn-settings: The name of the settings file with credentials for the project.
221 .. comment Start ignoring WriteGoodLintBear
223 :Optional parameters:
225 :branch: Git branch, should be master (default: master)
226 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
227 :build-timeout: Timeout in minutes before aborting build. (default: 60)
228 :cron: Cron schedule when to trigger the job. This parameter also
229 supports multiline input via YAML pipe | character in cases where
230 one may want to provide more than 1 cron timer. (default: H 11 * * *
232 :disable-job: Whether to disable the job (default: false)
233 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
234 :github-url: URL for Github. (default: https://github.com)
235 :java-version: Version of Java to use for the build. (default: openjdk11)
236 :mvn-global-settings: The name of the Maven global settings to use
237 :mvn-goals: The Maven goal to run first. (default: validate)
238 :mvn-version: Version of maven to use. (default: mvn35)
239 :parallel: If different from false, try pass this parameter to tox option
240 "--parallel" to parallelize jobs in the envlist (and then activate the
241 option "--parallel-live" to display output in logs).
242 Possible values are "auto" (equivalent to "true" for legacy),
243 "all" or any integer. Any other value is equivalent to "false".
244 (default: false, in series)
245 :pre-build-script: Shell script to execute before the Sonar builder.
246 For example, install prerequisites or move files to the repo root.
247 (default: a string with a shell comment)
248 :python-version: Python version to invoke pip install of tox-pyenv
250 :sonarcloud-project-key: SonarCloud project key. (default: '')
251 :sonarcloud-project-organization: SonarCloud project organization.
253 :sonarcloud-api-token-cred-id: Jenkins credential ID which has the SonarCloud API Token.
254 This one SHOULDN'T be overwritten as per we are standarizing the credential ID for all
255 projects (default: 'sonarcloud-api-token')
256 :sonar-scanner-home: Sonar scanner home directory.
257 (default: $WORKSPACE/.sonar/sonar-scanner-$SONAR_SCANNER_VERSION-linux)
258 :sonar-scanner-opts: Sonar scanner Java options. (default: '-server')
259 :sonar-scanner-version: Version of sonar scanner to use. (default: 4.7.0.2747)
260 :stream: Keyword used to represent a release code-name.
261 Often the same as the branch. (default: master)
262 :submodule-recursive: Whether to checkout submodules recursively.
264 :submodule-timeout: Timeout (in minutes) for checkout operation.
266 :submodule-disable: Disable submodule checkout operation.
268 :tox-dir: Directory containing the project's tox.ini relative to
269 the workspace. The default uses tox.ini at the project root.
271 :tox-envs: Tox environments to run. If blank run everything described
272 in tox.ini. (default: '')
273 :gerrit_sonar_triggers: Override Gerrit Triggers.
274 :gerrit_trigger_file_paths: Override file paths used to filter which file
275 modifications trigger a build. Refer to JJB documentation for "file-path" details.
276 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
278 .. comment Stop ignoring
280 Python Sonar with Tox
281 ---------------------
283 Sonar scans for Python based repos. This job invokes tox to run tests
284 and gather coverage statistics from the test results, then invokes
285 Maven to publish the results to either a Sonar server or SonarCloud.
287 **Deprecated**, new projects should use Tox Sonarqube.
289 To get the Sonar coverage results, file tox.ini must exist and contain
290 coverage commands to run.
292 The coverage commands define the code that gets executed by the test
293 suites. Checking coverage does not guarantee that the tests execute
294 properly, but it identifies code that is not executed by any test.
296 This job reuses the Sonar builders used for Java/Maven projects which
297 run maven twice. The first invocation does nothing for Python
298 projects, so the job uses the goal ``validate`` by default. The second
299 invocation publishes results using the goal ``sonar:sonar`` by default.
307 coverage run --module pytest --junitxml xunit-results.xml
308 coverage xml --omit=".tox/py3/*","tests/*"
309 coverage report --omit=".tox/py3/*","tests/*"
311 For more details refer to coverage and sonar documentation:
313 https://coverage.readthedocs.io/
315 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
319 - {project-name}-tox-sonar
323 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
324 this job manually. Do not include any other text or vote in the
327 :Required parameters:
329 :build-node: The node to run build on.
330 :jenkins-ssh-credential: Credential to use for SSH. (Generally should
331 get configured in defaults.yaml)
332 :mvn-settings: The name of the settings file with credentials for the project.
334 .. comment Start ignoring WriteGoodLintBear
336 :Optional parameters:
338 :branch: Git branch, should be master (default: master)
339 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
340 :build-timeout: Timeout in minutes before aborting build. (default: 60)
341 :cron: Cron schedule when to trigger the job. This parameter also
342 supports multiline input via YAML pipe | character in cases where
343 one may want to provide more than 1 cron timer. (default: H 11 * * *
345 :disable-job: Whether to disable the job (default: false)
346 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
347 :github-url: URL for Github. (default: https://github.com)
348 :java-version: Version of Java to use for the build. (default: openjdk11)
349 :mvn-global-settings: The name of the Maven global settings to use
350 :mvn-goals: The Maven goal to run first. (default: validate)
351 :mvn-version: Version of maven to use. (default: mvn35)
352 :parallel: If different from false, try pass this parameter to tox option
353 "--parallel" to parallelize jobs in the envlist (and then activate the
354 option "--parallel-live" to display output in logs).
355 Possible values are "auto" (equivalent to "true" for legacy),
356 "all" or any integer. Any other value is equivalent to "false".
357 (default: false, in series)
358 :pre-build-script: Shell script to execute before the Sonar builder.
359 For example, install prerequisites or move files to the repo root.
360 (default: a string with a shell comment)
361 :python-version: Python version to invoke pip install of tox-pyenv
363 :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
365 :sonarcloud-project-key: SonarCloud project key. (default: '')
366 :sonarcloud-project-organization: SonarCloud project organization.
368 :sonarcloud-api-token-cred-id: Jenkins credential ID which has the SonarCloud API Token.
369 This one SHOULDN'T be overwritten as per we are standarizing the credential ID for all
370 projects (default: 'sonarcloud-api-token')
371 :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
372 :stream: Keyword used to represent a release code-name.
373 Often the same as the branch. (default: master)
374 :submodule-recursive: Whether to checkout submodules recursively.
376 :submodule-timeout: Timeout (in minutes) for checkout operation.
378 :submodule-disable: Disable submodule checkout operation.
380 :tox-dir: Directory containing the project's tox.ini relative to
381 the workspace. The default uses tox.ini at the project root.
383 :tox-envs: Tox environments to run. If blank run everything described
384 in tox.ini. (default: '')
385 :gerrit_sonar_triggers: Override Gerrit Triggers.
386 :gerrit_trigger_file_paths: Override file paths used to filter which file
387 modifications trigger a build. Refer to JJB documentation for "file-path" details.
388 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
390 .. comment Stop ignoring
396 The SonarQube job invokes tox to run tests and generate code-coverage
397 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
398 code, gather coverage data, and upload the results to a SonarQube server
399 such as SonarCloud.io. Optionally runs a shell script before tox.
401 Requires ``SonarQube Scanner for Jenkins``
403 This job runs on the master branch because the basic Sonar configuration
404 does not support multi-branch.
406 Plug-in configurations
407 Manage Jenkins --> Configure System --> SonarQube servers
408 - Name: Sonar (fixed)
409 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
410 - Server authentication token: none for local, API token (saved as
411 a "secret text" credential) for Sonarcloud
413 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
414 - Name: SonarQube Scanner (fixed)
415 - Install automatically
416 - Select latest version
420 - {project-name}-tox-sonarqube
421 - gerrit-tox-sonarqube
422 - github-tox-sonarqube
424 :Comment Trigger: ``run-sonar``
426 :Required parameters:
428 :build-node: The node to run the build on.
429 (Commonly in defaults.yaml)
430 :jenkins-ssh-credential: Credential to use for SSH.
431 (Commonly in defaults.yaml)
432 :project: The git repository name.
433 :project-name: Prefix used to name jobs.
435 .. comment Start ignoring WriteGoodLintBear
437 :Optional Parameters:
439 :archive-artifacts: Pattern for files to archive to the logs server
440 (default: '\*\*/\*.log')
441 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
442 :build-timeout: Timeout in minutes before aborting build. (default: 15)
443 :cron: Cron schedule when to trigger the job. This parameter also
444 supports multiline input via YAML pipe | character in cases where
445 one may want to provide more than 1 cron timer. (default: @weekly)
446 :disable-job: Whether to disable the job (default: false)
447 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
448 :github-url: URL for Github. (default: https://github.com)
449 :parallel: If different from false, try pass this parameter to tox option
450 "--parallel" to parallelize jobs in the envlist (and then activate the
451 option "--parallel-live" to display output in logs).
452 Possible values are "auto" (equivalent to "true" for legacy),
453 "all" or any integer. Any other value is equivalent to "false".
454 (default: false, in series)
455 :pre-build-script: Shell script to run before tox. Useful for setting up
456 dependencies. (default: a string with a shell comment)
457 :python-version: Python version to invoke pip install of tox-pyenv
459 :sonar-additional-args: Command line arguments. (default: '')
460 :sonar-java-opts: JVM options. For example, use option -Xmx
461 to increase the memory size limit. (default: '')
462 :sonar-jdk: JDK version to use. (default: openjdk17)
463 :sonar-project-file: The file name with Sonar configuration properties
464 (default: sonar-project.properties)
465 :sonar-properties: Sonar configuration properties. (default: '')
466 :sonar-task: Sonar task to run. (default: '')
467 :tox-dir: Directory containing the project's tox.ini relative to
468 the workspace. The default uses tox.ini at the project root.
470 :tox-envs: Tox environments to run. If blank run everything described
471 in tox.ini. (default: '')
473 .. comment Stop ignoring
475 .. note:: A job definition must provide one of the optional parameters
476 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
477 empty. Set Sonar properties directly in the job definition by setting
478 the ``sonar-project-file`` property to ``""`` and adding all properties
479 under ``sonar-properties``.
481 :Required Sonar Properties:
483 - sonar.login: The API token for authentication at SonarCloud.
484 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
485 - sonar.organization: The umbrella project name; e.g., "opendaylight".
486 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
487 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
488 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
489 teams use the catenation of sonar.organization, an underscore, and
490 sonar.projectName; e.g., "opendaylight_infrautils".
492 :Optional Sonar Properties:
494 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
495 - Documentation of SonarQube properties is here:
496 https://docs.sonarqube.org/latest/analysis/overview/
499 Example job definition
500 ^^^^^^^^^^^^^^^^^^^^^^
502 The following example defines a job for a basic Python project. This definition
503 uses configuration parameters in the umbrella project's defaults.yaml file.
508 name: my-package-sonar
510 project-name: my-package
511 sonar-project-file: ""
513 sonar.login={sonarcloud_api_token}
514 sonar.projectKey={sonarcloud_project_organization}_{project-name}
515 sonar.projectName={project-name}
516 sonar.organization={sonarcloud_project_organization}
517 sonar.sourceEncoding=UTF-8
518 sonar.sources=mypackage
519 sonar.exclusions=tests/*,setup.py
520 sonar.python.coverage.reportPaths=coverage.xml
522 - gerrit-tox-sonarqube
528 Tox runner to verify a project on creation of a patch set. This job
529 is pyenv aware so if the image contains an installation of pyenv at
530 /opt/pyenv it will pick it up and run Python tests with the
531 appropriate Python versions. This job will set the following pyenv
532 variables before running.
536 export PYENV_ROOT="/opt/pyenv"
537 export PATH="$PYENV_ROOT/bin:$PATH"
541 - {project-name}-tox-verify-{stream}
545 :Comment Trigger: **recheck|reverify** post a comment with one of the
546 triggers to launch this job manually. Do not include any other
547 text or vote in the same comment.
549 :Required Parameters:
551 :build-node: The node to run build on.
552 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
555 :Optional Parameters:
557 :branch: The branch to build against. (default: master)
558 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
559 :build-timeout: Timeout in minutes before aborting build. (default: 10)
560 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
561 :pre-build-script: Shell script to execute before the Tox builder.
562 For example, install prerequisites or move files to the repo root.
563 (default: a string with a shell comment)
564 :parallel: If different from false, try pass this parameter to tox option
565 "--parallel" to parallelize jobs in the envlist (and then activate the
566 option "--parallel-live" to display output in logs).
567 Possible values are "auto" (equivalent to "true" for legacy),
568 "all" or any integer. Any other value is equivalent to "false".
569 (default: false, in series)
570 :python-version: Python version to invoke pip install of tox-pyenv
572 :stream: Keyword representing a release code-name.
573 Often the same as the branch. (default: master)
574 :submodule-recursive: Whether to checkout submodules recursively.
576 :submodule-timeout: Timeout (in minutes) for checkout operation.
578 :submodule-disable: Disable submodule checkout operation.
580 :tox-dir: Directory containing the project's tox.ini relative to
581 the workspace. The default uses tox.ini at the project root.
583 :tox-envs: Tox environments to run. If blank run everything described
584 in tox.ini. (default: '')
585 :gerrit_trigger_file_paths: Override file paths used to filter which file
586 modifications trigger a build. Refer to JJB documentation for "file-path" details.
587 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
593 Tox runner to verify a project after merge of a patch set. This job
594 is pyenv aware so if the image contains an installation of pyenv at
595 /opt/pyenv it will pick it up and run Python tests with the
596 appropriate Python versions. This job will set the following pyenv
597 variables before running.
601 export PYENV_ROOT="/opt/pyenv"
602 export PATH="$PYENV_ROOT/bin:$PATH"
606 - {project-name}-tox-merge-{stream}
610 :Comment Trigger: **remerge** post a comment with the trigger to launch
611 this job manually. Do not include any other text or vote in the
614 :Required Parameters:
616 :build-node: The node to run build on.
617 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
620 :Optional Parameters:
622 :branch: The branch to build against. (default: master)
623 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
624 :build-timeout: Timeout in minutes before aborting build. (default: 10)
625 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
626 :pre-build-script: Shell script to execute before the CLM builder.
627 For example, install prerequisites or move files to the repo root.
628 (default: a string with a shell comment)
629 :python-version: Python version to invoke pip install of tox-pyenv
631 :stream: Keyword representing a release code-name.
632 Often the same as the branch. (default: master)
633 :submodule-recursive: Whether to checkout submodules recursively.
635 :submodule-timeout: Timeout (in minutes) for checkout operation.
637 :submodule-disable: Disable submodule checkout operation.
639 :tox-dir: Directory containing the project's tox.ini relative to
640 the workspace. The default uses tox.ini at the project root.
642 :tox-envs: Tox environments to run. If blank run everything described
643 in tox.ini. (default: '')
644 :gerrit_trigger_file_paths: Override file paths used to filter which file
645 modifications trigger a build. Refer to JJB documentation for "file-path" details.
646 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
652 Creates and uploads package distribution files on merge of a patch set.
653 Runs tox, builds a source distribution and (optionally) a binary
654 distribution, and uploads the distribution(s) to a PyPI repository.
655 The project git repository must have a setup.py file
656 with configuration for packaging the component.
658 Projects can choose **either** this template to publish on merge,
659 **or** the Stage template to publish on command.
661 This job should use a staging repository like testpypi.python.org,
662 which sets up use of release jobs to promote the distributions later.
663 This job can also use a public release area like the global PyPI
664 repository if the release process is not needed. These PyPI
665 repositories allow upload of a package at a specific version once,
666 they do not allow overwrite of a package. This means that a merge job
667 will fail in the upload step if the package version already exists in
668 the target repository.
670 The tox runner is pyenv aware so if the image contains an installation
671 of pyenv at /opt/pyenv it will pick it up and run Python tests with
672 the appropriate Python versions. The tox runner sets the following
673 pyenv variables before running.
677 export PYENV_ROOT="/opt/pyenv"
678 export PATH="$PYENV_ROOT/bin:$PATH"
680 See the recommended directory layout documented in the PyPI Verify job.
682 Jobs using this PyPI template depend on a .pypirc configuration file
683 in the Jenkins builder home directory. An example appears next that uses
684 API tokens. Note that in the [pypi] entry the repository key-value pair
685 is optional, it defaults to pypi.org.
689 [distutils] # this tells distutils what package indexes you can push to
690 index-servers = pypi-test pypi
693 repository: https://test.pypi.org/legacy/
695 password: pypi-test-api-token-goes-here
699 password: pypi-api-token-goes-here
704 - {project-name}-pypi-merge-{stream}
708 :Comment Trigger: **remerge** post a comment with the trigger to launch
709 this job manually. Do not include any other text or vote in the
712 :Required Parameters:
714 :build-node: The node to run the build on.
715 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
717 :mvn-settings: The settings file with credentials for the project
718 :project: Git repository name
719 :project-name: Jenkins job name prefix
721 :Optional Parameters:
723 :branch: The branch to build against. (default: master)
724 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
725 :build-timeout: Timeout in minutes before aborting build. (default: 15)
726 :cron: Cron schedule when to trigger the job. Supports regular builds.
727 Not useful when publishing to pypi.org because that rejects a package
728 if the version exists. (default: empty)
729 :disable-job: Whether to disable the job (default: false)
730 :dist-binary: Whether to build a binary wheel distribution. (default: true)
731 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
732 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
733 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
734 :mvn-version: Version of maven to use. (default: mvn35)
735 :parallel: If different from false, try pass this parameter to tox option
736 "--parallel" to parallelize jobs in the envlist (and then activate the
737 option "--parallel-live" to display output in logs).
738 Possible values are "auto" (equivalent to "true" for legacy),
739 "all" or any integer. Any other value is equivalent to "false".
740 (default: false, in series)
741 :pre-build-script: Shell script to execute before the tox builder. For
742 example, install system prerequisites. (default: a shell comment)
743 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
744 ideally a server like test.pypi.org. (default: pypi-test)
745 :python-version: Python version to invoke pip install of tox-pyenv
747 :stream: Keyword representing a release code-name.
748 Often the same as the branch. (default: master)
749 :submodule-recursive: Whether to checkout submodules recursively.
751 :submodule-timeout: Timeout (in minutes) for checkout operation.
753 :submodule-disable: Disable submodule checkout operation.
755 :tox-dir: Directory containing the project's tox.ini relative to
756 the workspace. The default uses tox.ini at the project root.
758 :tox-envs: Tox environments to run. If blank run everything described
759 in tox.ini. (default: '')
760 :gerrit_trigger_file_paths: Override file paths used to filter which file
761 modifications trigger a build. Refer to JJB documentation for "file-path" details.
762 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
768 Creates and uploads package distribution files on receipt of a comment.
769 Runs tox, builds a source distribution and (optionally) a binary
770 distribution, and uploads the distribution(s) to a PyPI repository.
771 The project git repository must have a setup.py file with configuration
772 for packaging the component.
774 Projects can choose **either** this template to publish on command,
775 **or** the Merge template to publish on merge.
777 This job should use a staging repository like testpypi.python.org,
778 which sets up use of release jobs to promote the distributions later.
779 This job can also use a public release area like the global PyPI
780 repository if the release process is not needed. These PyPI
781 repositories allow upload of a package at a specific version once,
782 they do not allow overwrite of a package. This means that a job
783 will fail in the upload step if the package version already exists in
784 the target repository.
786 The tox runner is pyenv aware so if the image contains an installation
787 of pyenv at /opt/pyenv it will pick it up and run Python tests with
788 the appropriate Python versions. The tox runner sets the following
789 pyenv variables before running.
793 export PYENV_ROOT="/opt/pyenv"
794 export PATH="$PYENV_ROOT/bin:$PATH"
796 See the recommended directory layout documented in the PyPI Verify job.
798 Jobs using this PyPI template depend on a .pypirc configuration file
799 in the Jenkins builder home directory. An example appears next that uses
800 API tokens. Note that in the [pypi] entry the repository key-value pair
801 is optional, it defaults to pypi.org.
805 [distutils] # this tells distutils what package indexes you can push to
806 index-servers = pypi-test pypi
809 repository: https://test.pypi.org/legacy/
811 password: pypi-test-api-token-goes-here
815 password: pypi-api-token-goes-here
820 - {project-name}-pypi-stage-{stream}
824 :Comment Trigger: **stage-release** post a comment with the trigger to launch
825 this job manually. Do not include any other text or vote in the
828 :Required Parameters:
830 :build-node: The node to run the build on.
831 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
833 :mvn-settings: The settings file with credentials for the project
834 :project: Git repository name
835 :project-name: Jenkins job name prefix
837 :Optional Parameters:
839 :branch: The branch to build against. (default: master)
840 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
841 :build-timeout: Timeout in minutes before aborting build. (default: 15)
842 :cron: Cron schedule when to trigger the job. Supports regular builds.
843 Not useful when publishing to pypi.org because that rejects a package
844 if the version exists. (default: empty)
845 :disable-job: Whether to disable the job (default: false)
846 :dist-binary: Whether to build a binary wheel distribution. (default: true)
847 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
848 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
849 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
850 :mvn-version: Version of maven to use. (default: mvn35)
851 :parallel: If different from false, try pass this parameter to tox option
852 "--parallel" to parallelize jobs in the envlist (and then activate the
853 option "--parallel-live" to display output in logs).
854 Possible values are "auto" (equivalent to "true" for legacy),
855 "all" or any integer. Any other value is equivalent to "false".
856 (default: false, in series)
857 :pre-build-script: Shell script to execute before the tox builder. For
858 example, install system prerequisites. (default: a shell comment)
859 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
860 ideally a server like test.pypi.org. (default: pypi-test)
861 :python-version: Python version to invoke pip install of tox-pyenv
863 :stream: Keyword representing a release code-name.
864 Often the same as the branch. (default: master)
865 :submodule-recursive: Whether to checkout submodules recursively.
867 :submodule-timeout: Timeout (in minutes) for checkout operation.
869 :submodule-disable: Disable submodule checkout operation.
871 :tox-dir: Directory containing the project's tox.ini relative to
872 the workspace. The default uses tox.ini at the project root.
874 :tox-envs: Tox environments to run. If blank run everything described
875 in tox.ini. (default: '')
876 :gerrit_trigger_file_paths: Override file paths used to filter which file
877 modifications trigger a build. Refer to JJB documentation for "file-path" details.
878 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
883 Verifies a Python library project on creation of a patch set. Runs tox
884 then builds a source distribution and (optionally) a binary
885 distribution. The project repository must have a setup.py file with
886 configuration for packaging the component.
888 Installable package projects should use the directory layout shown
889 below. All Python files are in a repo subdirectory separate from
890 non-Python files like documentation. This layout allows highly
891 specific build-job triggers in Jenkins using the subdirectory
892 paths. For example, a PyPI publisher job should not run on a non-Python
893 file change such as documentation, because the job cannot upload the
896 To make the document files available for building a Python package
897 long description in setup.py, add a symbolic link "docs" in the
898 package subdirectory pointing to the top-level docs directory.
906 │ └── release-notes.rst
908 ├── helloworld-package/
912 │ │ ├── helloworld.py
916 │ │ ├── helloworld_tests.py
917 │ │ └── helloworld_mocks.py
919 │ ├── requirements.txt
924 │ └── pypi-helloworld.yaml
931 The tox runner is pyenv aware so if the image contains an installation
932 of pyenv at /opt/pyenv it will pick it up and run Python tests with
933 the appropriate Python versions. The tox runner sets the following
934 pyenv variables before running.
938 export PYENV_ROOT="/opt/pyenv"
939 export PATH="$PYENV_ROOT/bin:$PATH"
943 - {project-name}-pypi-verify-{stream}
947 :Comment Trigger: **recheck|reverify** post a comment with one of the
948 triggers to launch this job manually. Do not include any other
949 text or vote in the same comment.
951 :Required Parameters:
953 :build-node: The node to run the build on.
954 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
956 :mvn-settings: The settings file with credentials for the project
957 :project: Git repository name
958 :project-name: Jenkins job name prefix
960 :Optional Parameters:
962 :branch: The branch to build against. (default: master)
963 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
964 :build-timeout: Timeout in minutes before aborting build. (default: 15)
965 :disable-job: Whether to disable the job (default: false)
966 :dist-binary: Whether to build a binary wheel distribution. (default: true)
967 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
968 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
969 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
970 :mvn-version: Version of maven to use. (default: mvn35)
971 :parallel: If different from false, try pass this parameter to tox option
972 "--parallel" to parallelize jobs in the envlist (and then activate the
973 option "--parallel-live" to display output in logs).
974 Possible values are "auto" (equivalent to "true" for legacy),
975 "all" or any integer. Any other value is equivalent to "false".
976 (default: false, in series)
977 :pre-build-script: Shell script to execute before the tox builder. For
978 example, install system prerequisites. (default: a shell comment)
979 :python-version: Python version to invoke pip install of tox-pyenv
981 :stream: Keyword representing a release code-name.
982 Often the same as the branch. (default: master)
983 :submodule-recursive: Whether to checkout submodules recursively.
985 :submodule-timeout: Timeout (in minutes) for checkout operation.
987 :submodule-disable: Disable submodule checkout operation.
989 :tox-dir: Directory containing the project's tox.ini relative to
990 the workspace. The default uses tox.ini at the project root.
992 :tox-envs: Tox environments to run. If blank run everything described
993 in tox.ini. (default: '')
994 :gerrit_trigger_file_paths: Override file paths used to filter which file
995 modifications trigger a build. Refer to JJB documentation for "file-path" details.
996 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit