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.
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-project-file: The file name with Sonar configuration properties
463 (default: sonar-project.properties)
464 :sonar-properties: Sonar configuration properties. (default: '')
465 :sonar-task: Sonar task to run. (default: '')
466 :tox-dir: Directory containing the project's tox.ini relative to
467 the workspace. The default uses tox.ini at the project root.
469 :tox-envs: Tox environments to run. If blank run everything described
470 in tox.ini. (default: '')
472 .. comment Stop ignoring
474 .. note:: A job definition must provide one of the optional parameters
475 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
476 empty. Set Sonar properties directly in the job definition by setting
477 the ``sonar-project-file`` property to ``""`` and adding all properties
478 under ``sonar-properties``.
480 :Required Sonar Properties:
482 - sonar.login: The API token for authentication at SonarCloud.
483 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
484 - sonar.organization: The umbrella project name; e.g., "opendaylight".
485 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
486 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
487 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
488 teams use the catenation of sonar.organization, an underscore, and
489 sonar.projectName; e.g., "opendaylight_infrautils".
491 :Optional Sonar Properties:
493 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
494 - Documentation of SonarQube properties is here:
495 https://docs.sonarqube.org/latest/analysis/overview/
498 Example job definition
499 ^^^^^^^^^^^^^^^^^^^^^^
501 The following example defines a job for a basic Python project. This definition
502 uses configuration parameters in the umbrella project's defaults.yaml file.
507 name: my-package-sonar
509 project-name: my-package
510 sonar-project-file: ""
512 sonar.login={sonarcloud_api_token}
513 sonar.projectKey={sonarcloud_project_organization}_{project-name}
514 sonar.projectName={project-name}
515 sonar.organization={sonarcloud_project_organization}
516 sonar.sourceEncoding=UTF-8
517 sonar.sources=mypackage
518 sonar.exclusions=tests/*,setup.py
519 sonar.python.coverage.reportPaths=coverage.xml
521 - gerrit-tox-sonarqube
527 Tox runner to verify a project on creation of a patch set. This job
528 is pyenv aware so if the image contains an installation of pyenv at
529 /opt/pyenv it will pick it up and run Python tests with the
530 appropriate Python versions. This job will set the following pyenv
531 variables before running.
535 export PYENV_ROOT="/opt/pyenv"
536 export PATH="$PYENV_ROOT/bin:$PATH"
540 - {project-name}-tox-verify-{stream}
544 :Comment Trigger: **recheck|reverify** post a comment with one of the
545 triggers to launch this job manually. Do not include any other
546 text or vote in the same comment.
548 :Required Parameters:
550 :build-node: The node to run build on.
551 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
554 :Optional Parameters:
556 :branch: The branch to build against. (default: master)
557 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
558 :build-timeout: Timeout in minutes before aborting build. (default: 10)
559 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
560 :pre-build-script: Shell script to execute before the Tox builder.
561 For example, install prerequisites or move files to the repo root.
562 (default: a string with a shell comment)
563 :parallel: If different from false, try pass this parameter to tox option
564 "--parallel" to parallelize jobs in the envlist (and then activate the
565 option "--parallel-live" to display output in logs).
566 Possible values are "auto" (equivalent to "true" for legacy),
567 "all" or any integer. Any other value is equivalent to "false".
568 (default: false, in series)
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 Tox runner to verify a project after merge of a patch set. This job
593 is pyenv aware so if the image contains an installation of pyenv at
594 /opt/pyenv it will pick it up and run Python tests with the
595 appropriate Python versions. This job will set the following pyenv
596 variables before running.
600 export PYENV_ROOT="/opt/pyenv"
601 export PATH="$PYENV_ROOT/bin:$PATH"
605 - {project-name}-tox-merge-{stream}
609 :Comment Trigger: **remerge** post a comment with the trigger to launch
610 this job manually. Do not include any other text or vote in the
613 :Required Parameters:
615 :build-node: The node to run build on.
616 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
619 :Optional Parameters:
621 :branch: The branch to build against. (default: master)
622 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
623 :build-timeout: Timeout in minutes before aborting build. (default: 10)
624 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
625 :pre-build-script: Shell script to execute before the CLM builder.
626 For example, install prerequisites or move files to the repo root.
627 (default: a string with a shell comment)
628 :python-version: Python version to invoke pip install of tox-pyenv
630 :stream: Keyword representing a release code-name.
631 Often the same as the branch. (default: master)
632 :submodule-recursive: Whether to checkout submodules recursively.
634 :submodule-timeout: Timeout (in minutes) for checkout operation.
636 :submodule-disable: Disable submodule checkout operation.
638 :tox-dir: Directory containing the project's tox.ini relative to
639 the workspace. The default uses tox.ini at the project root.
641 :tox-envs: Tox environments to run. If blank run everything described
642 in tox.ini. (default: '')
643 :gerrit_trigger_file_paths: Override file paths used to filter which file
644 modifications trigger a build. Refer to JJB documentation for "file-path" details.
645 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
651 Creates and uploads package distribution files on merge of a patch set.
652 Runs tox, builds a source distribution and (optionally) a binary
653 distribution, and uploads the distribution(s) to a PyPI repository.
654 The project git repository must have a setup.py file
655 with configuration for packaging the component.
657 Projects can choose **either** this template to publish on merge,
658 **or** the Stage template to publish on command.
660 This job should use a staging repository like testpypi.python.org,
661 which sets up use of release jobs to promote the distributions later.
662 This job can also use a public release area like the global PyPI
663 repository if the release process is not needed. These PyPI
664 repositories allow upload of a package at a specific version once,
665 they do not allow overwrite of a package. This means that a merge job
666 will fail in the upload step if the package version already exists in
667 the target repository.
669 The tox runner is pyenv aware so if the image contains an installation
670 of pyenv at /opt/pyenv it will pick it up and run Python tests with
671 the appropriate Python versions. The tox runner sets the following
672 pyenv variables before running.
676 export PYENV_ROOT="/opt/pyenv"
677 export PATH="$PYENV_ROOT/bin:$PATH"
679 See the recommended directory layout documented in the PyPI Verify job.
681 Jobs using this PyPI template depend on a .pypirc configuration file
682 in the Jenkins builder home directory. An example appears next that uses
683 API tokens. Note that in the [pypi] entry the repository key-value pair
684 is optional, it defaults to pypi.org.
688 [distutils] # this tells distutils what package indexes you can push to
689 index-servers = pypi-test pypi
692 repository: https://test.pypi.org/legacy/
694 password: pypi-test-api-token-goes-here
698 password: pypi-api-token-goes-here
703 - {project-name}-pypi-merge-{stream}
707 :Comment Trigger: **remerge** post a comment with the trigger to launch
708 this job manually. Do not include any other text or vote in the
711 :Required Parameters:
713 :build-node: The node to run the build on.
714 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
716 :mvn-settings: The settings file with credentials for the project
717 :project: Git repository name
718 :project-name: Jenkins job name prefix
720 :Optional Parameters:
722 :branch: The branch to build against. (default: master)
723 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
724 :build-timeout: Timeout in minutes before aborting build. (default: 15)
725 :cron: Cron schedule when to trigger the job. Supports regular builds.
726 Not useful when publishing to pypi.org because that rejects a package
727 if the version exists. (default: empty)
728 :disable-job: Whether to disable the job (default: false)
729 :dist-binary: Whether to build a binary wheel distribution. (default: true)
730 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
731 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
732 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
733 :mvn-version: Version of maven to use. (default: mvn35)
734 :parallel: If different from false, try pass this parameter to tox option
735 "--parallel" to parallelize jobs in the envlist (and then activate the
736 option "--parallel-live" to display output in logs).
737 Possible values are "auto" (equivalent to "true" for legacy),
738 "all" or any integer. Any other value is equivalent to "false".
739 (default: false, in series)
740 :pre-build-script: Shell script to execute before the tox builder. For
741 example, install system prerequisites. (default: a shell comment)
742 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
743 ideally a server like test.pypi.org. (default: pypi-test)
744 :python-version: Python version to invoke pip install of tox-pyenv
746 :stream: Keyword representing a release code-name.
747 Often the same as the branch. (default: master)
748 :submodule-recursive: Whether to checkout submodules recursively.
750 :submodule-timeout: Timeout (in minutes) for checkout operation.
752 :submodule-disable: Disable submodule checkout operation.
754 :tox-dir: Directory containing the project's tox.ini relative to
755 the workspace. The default uses tox.ini at the project root.
757 :tox-envs: Tox environments to run. If blank run everything described
758 in tox.ini. (default: '')
759 :gerrit_trigger_file_paths: Override file paths used to filter which file
760 modifications trigger a build. Refer to JJB documentation for "file-path" details.
761 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
767 Creates and uploads package distribution files on receipt of a comment.
768 Runs tox, builds a source distribution and (optionally) a binary
769 distribution, and uploads the distribution(s) to a PyPI repository.
770 The project git repository must have a setup.py file with configuration
771 for packaging the component.
773 Projects can choose **either** this template to publish on command,
774 **or** the Merge template to publish on merge.
776 This job should use a staging repository like testpypi.python.org,
777 which sets up use of release jobs to promote the distributions later.
778 This job can also use a public release area like the global PyPI
779 repository if the release process is not needed. These PyPI
780 repositories allow upload of a package at a specific version once,
781 they do not allow overwrite of a package. This means that a job
782 will fail in the upload step if the package version already exists in
783 the target repository.
785 The tox runner is pyenv aware so if the image contains an installation
786 of pyenv at /opt/pyenv it will pick it up and run Python tests with
787 the appropriate Python versions. The tox runner sets the following
788 pyenv variables before running.
792 export PYENV_ROOT="/opt/pyenv"
793 export PATH="$PYENV_ROOT/bin:$PATH"
795 See the recommended directory layout documented in the PyPI Verify job.
797 Jobs using this PyPI template depend on a .pypirc configuration file
798 in the Jenkins builder home directory. An example appears next that uses
799 API tokens. Note that in the [pypi] entry the repository key-value pair
800 is optional, it defaults to pypi.org.
804 [distutils] # this tells distutils what package indexes you can push to
805 index-servers = pypi-test pypi
808 repository: https://test.pypi.org/legacy/
810 password: pypi-test-api-token-goes-here
814 password: pypi-api-token-goes-here
819 - {project-name}-pypi-stage-{stream}
823 :Comment Trigger: **stage-release** post a comment with the trigger to launch
824 this job manually. Do not include any other text or vote in the
827 :Required Parameters:
829 :build-node: The node to run the build on.
830 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
832 :mvn-settings: The settings file with credentials for the project
833 :project: Git repository name
834 :project-name: Jenkins job name prefix
836 :Optional Parameters:
838 :branch: The branch to build against. (default: master)
839 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
840 :build-timeout: Timeout in minutes before aborting build. (default: 15)
841 :cron: Cron schedule when to trigger the job. Supports regular builds.
842 Not useful when publishing to pypi.org because that rejects a package
843 if the version exists. (default: empty)
844 :disable-job: Whether to disable the job (default: false)
845 :dist-binary: Whether to build a binary wheel distribution. (default: true)
846 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
847 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
848 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
849 :mvn-version: Version of maven to use. (default: mvn35)
850 :parallel: If different from false, try pass this parameter to tox option
851 "--parallel" to parallelize jobs in the envlist (and then activate the
852 option "--parallel-live" to display output in logs).
853 Possible values are "auto" (equivalent to "true" for legacy),
854 "all" or any integer. Any other value is equivalent to "false".
855 (default: false, in series)
856 :pre-build-script: Shell script to execute before the tox builder. For
857 example, install system prerequisites. (default: a shell comment)
858 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
859 ideally a server like test.pypi.org. (default: pypi-test)
860 :python-version: Python version to invoke pip install of tox-pyenv
862 :stream: Keyword representing a release code-name.
863 Often the same as the branch. (default: master)
864 :submodule-recursive: Whether to checkout submodules recursively.
866 :submodule-timeout: Timeout (in minutes) for checkout operation.
868 :submodule-disable: Disable submodule checkout operation.
870 :tox-dir: Directory containing the project's tox.ini relative to
871 the workspace. The default uses tox.ini at the project root.
873 :tox-envs: Tox environments to run. If blank run everything described
874 in tox.ini. (default: '')
875 :gerrit_trigger_file_paths: Override file paths used to filter which file
876 modifications trigger a build. Refer to JJB documentation for "file-path" details.
877 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit
882 Verifies a Python library project on creation of a patch set. Runs tox
883 then builds a source distribution and (optionally) a binary
884 distribution. The project repository must have a setup.py file with
885 configuration for packaging the component.
887 Installable package projects should use the directory layout shown
888 below. All Python files are in a repo subdirectory separate from
889 non-Python files like documentation. This layout allows highly
890 specific build-job triggers in Jenkins using the subdirectory
891 paths. For example, a PyPI publisher job should not run on a non-Python
892 file change such as documentation, because the job cannot upload the
895 To make the document files available for building a Python package
896 long description in setup.py, add a symbolic link "docs" in the
897 package subdirectory pointing to the top-level docs directory.
905 │ └── release-notes.rst
907 ├── helloworld-package/
911 │ │ ├── helloworld.py
915 │ │ ├── helloworld_tests.py
916 │ │ └── helloworld_mocks.py
918 │ ├── requirements.txt
923 │ └── pypi-helloworld.yaml
930 The tox runner is pyenv aware so if the image contains an installation
931 of pyenv at /opt/pyenv it will pick it up and run Python tests with
932 the appropriate Python versions. The tox runner sets the following
933 pyenv variables before running.
937 export PYENV_ROOT="/opt/pyenv"
938 export PATH="$PYENV_ROOT/bin:$PATH"
942 - {project-name}-pypi-verify-{stream}
946 :Comment Trigger: **recheck|reverify** post a comment with one of the
947 triggers to launch this job manually. Do not include any other
948 text or vote in the same comment.
950 :Required Parameters:
952 :build-node: The node to run the build on.
953 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
955 :mvn-settings: The settings file with credentials for the project
956 :project: Git repository name
957 :project-name: Jenkins job name prefix
959 :Optional Parameters:
961 :branch: The branch to build against. (default: master)
962 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
963 :build-timeout: Timeout in minutes before aborting build. (default: 15)
964 :disable-job: Whether to disable the job (default: false)
965 :dist-binary: Whether to build a binary wheel distribution. (default: true)
966 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
967 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
968 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
969 :mvn-version: Version of maven to use. (default: mvn35)
970 :parallel: If different from false, try pass this parameter to tox option
971 "--parallel" to parallelize jobs in the envlist (and then activate the
972 option "--parallel-live" to display output in logs).
973 Possible values are "auto" (equivalent to "true" for legacy),
974 "all" or any integer. Any other value is equivalent to "false".
975 (default: false, in series)
976 :pre-build-script: Shell script to execute before the tox builder. For
977 example, install system prerequisites. (default: a shell comment)
978 :python-version: Python version to invoke pip install of tox-pyenv
980 :stream: Keyword representing a release code-name.
981 Often the same as the branch. (default: master)
982 :submodule-recursive: Whether to checkout submodules recursively.
984 :submodule-timeout: Timeout (in minutes) for checkout operation.
986 :submodule-disable: Disable submodule checkout operation.
988 :tox-dir: Directory containing the project's tox.ini relative to
989 the workspace. The default uses tox.ini at the project root.
991 :tox-envs: Tox environments to run. If blank run everything described
992 in tox.ini. (default: '')
993 :gerrit_trigger_file_paths: Override file paths used to filter which file
994 modifications trigger a build. Refer to JJB documentation for "file-path" details.
995 https://jenkins-job-builder.readthedocs.io/en/latest/triggers.html#triggers.gerrit