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: Boolean. If true use detox (distributed tox);
56 The Nexus IQ job invokes tox and the Nexus IQ scanner to analyze packages for
57 component lifecycle management (CLM). Runs tox to discover the required packages,
58 downloads the command-line interface (CLI) scanner, runs the scanner on the package
59 list, then uploads the results to a Nexus IQ server. The project's tox.ini file must
60 define a test environment that runs 'pip freeze' and captures the output; that
61 environment does not need to execute any tests. For example:
66 # use pip to report dependencies with versions
67 whitelist_externals = sh
68 commands = sh -c 'pip freeze > requirements.txt'
71 This job runs on the master branch because the basic Nexus IQ configuration
72 does not support multi-branch.
76 - {project-name}-tox-nexus-iq-clm
77 - gerrit-tox-nexus-iq-clm
78 - github-tox-nexus-iq-clm
80 :Comment Trigger: ``run-clm``
84 :build-node: The node to run the build on.
85 (Commonly in defaults.yaml)
86 :jenkins-ssh-credential: Credential to use for SSH.
87 (Commonly in defaults.yaml)
88 :project: The git repository name.
89 :project-name: Prefix used to name jobs.
93 :archive-artifacts: Pattern for files to archive to the logs server
94 (default: '\*\*/\*.log')
95 :branch: Git branch, should be master (default: master)
96 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
97 :build-timeout: Timeout in minutes before aborting build. (default: 15)
98 :cron: Cron schedule when to trigger the job. This parameter also
99 supports multiline input via the YAML pipe | character to allow
100 more than 1 cron timer. (default: @weekly)
101 :disable-job: Whether to disable the job (default: false)
102 :gerrit_nexusiq_triggers: Override Gerrit Triggers.
103 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
104 :github-url: URL for Github. (default: https://github.com)
105 :java-version: Version of Java to use for the scan. (default: openjdk8)
106 :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
107 (default is a string like 1.89.0-02, see file lf-python-jobs.yaml)
108 :nexus-iq-namespace: Insert a namespace to project AppID for projects that
109 share a Nexus IQ system to avoid project name collision. We recommend
110 inserting a trailing - dash if using this parameter.
111 For example 'odl-'. (default: '')
112 :pre-build-script: Shell script to run before tox. Useful for setting up
113 dependencies. (default: a string with a shell comment)
114 :python-version: Python version to invoke pip install of tox-pyenv
116 :requirements-file: Name of file with output of pip freeze.
117 (default: requirements.txt)
118 :submodule-recursive: Whether to checkout submodules recursively.
120 :submodule-timeout: Timeout (in minutes) for checkout operation.
122 :submodule-disable: Disable submodule checkout operation.
124 :tox-dir: Directory containing the project's tox.ini relative to
125 the workspace. The default uses tox.ini at the project root.
127 :tox-envs: Tox environment with the appropriate pip freeze invocation.
131 Python Sonar with Tox
132 ---------------------
134 Sonar scans for Python based repos. This job invokes tox to run tests
135 and gather coverage statistics from the test results, then invokes
136 Maven to publish the results to either a Sonar server or SonarCloud.
138 **Deprecated**, new projects should use Tox Sonarqube.
140 To get the Sonar coverage results, file tox.ini must exist and contain
141 coverage commands to run.
143 The coverage commands define the code that gets executed by the test
144 suites. Checking coverage does not guarantee that the tests execute
145 properly, but it identifies code that is not executed by any test.
147 .. comment Start ignoring WriteGoodLintBear
149 This job reuses the Sonar builders used for Java/Maven projects which
150 run maven twice. The first invocation does nothing for Python
151 projects, so the job uses the goal 'validate' by default. The second
152 invocation publishes results using the goal 'sonar:sonar' by default.
154 .. comment Stop ignoring
162 coverage run --module pytest --junitxml xunit-results.xml
163 coverage xml --omit=".tox/py27/*","tests/*"
164 coverage report --omit=".tox/py27/*","tests/*"
166 For more details refer to coverage and sonar documentation:
168 https://coverage.readthedocs.io/
170 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
174 - {project-name}-tox-sonar
178 :Comment Trigger: **run-sonar** post a comment with the trigger to launch
179 this job manually. Do not include any other text or vote in the
182 :Required parameters:
184 :build-node: The node to run build on.
185 :jenkins-ssh-credential: Credential to use for SSH. (Generally should
186 get configured in defaults.yaml)
187 :mvn-settings: The name of the settings file with credentials for the project.
189 .. comment Start ignoring WriteGoodLintBear
191 :Optional parameters:
193 :branch: Git branch, should be master (default: master)
194 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
195 :build-timeout: Timeout in minutes before aborting build. (default: 60)
196 :cron: Cron schedule when to trigger the job. This parameter also
197 supports multiline input via YAML pipe | character in cases where
198 one may want to provide more than 1 cron timer. (default: H 11 * * *
200 :disable-job: Whether to disable the job (default: false)
201 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
202 :github-url: URL for Github. (default: https://github.com)
203 :java-version: Version of Java to use for the build. (default: openjdk8)
204 :mvn-global-settings: The name of the Maven global settings to use
205 :mvn-goals: The Maven goal to run first. (default: validate)
206 :mvn-version: Version of maven to use. (default: mvn35)
207 :parallel: Boolean indicator for tox to run tests in parallel or series.
208 (default: false, in series)
209 :pre-build-script: Shell script to execute before the Sonar builder.
210 For example, install prerequisites or move files to the repo root.
211 (default: a string with a shell comment)
212 :python-version: Python version to invoke pip install of tox-pyenv
214 :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
216 :sonarcloud-project-key: SonarCloud project key. (default: '')
217 :sonarcloud-project-organization: SonarCloud project organization.
219 :sonarcloud-api-token: SonarCloud API Token. (default: '')
220 :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
221 :stream: Keyword used to represent a release code-name.
222 Often the same as the branch. (default: master)
223 :submodule-recursive: Whether to checkout submodules recursively.
225 :submodule-timeout: Timeout (in minutes) for checkout operation.
227 :submodule-disable: Disable submodule checkout operation.
229 :tox-dir: Directory containing the project's tox.ini relative to
230 the workspace. The default uses tox.ini at the project root.
232 :tox-envs: Tox environments to run. If blank run everything described
233 in tox.ini. (default: '')
234 :gerrit_sonar_triggers: Override Gerrit Triggers.
235 :gerrit_trigger_file_paths: Override file paths used to filter which file
236 modifications trigger a build. Refer to JJB documentation for "file-path" details.
237 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
239 .. comment Stop ignoring
245 The SonarQube job invokes tox to run tests and generate code-coverage
246 statistics, then runs the SonarQube Scanner Jenkins plug-in to analyze
247 code, gather coverage data, and upload the results to a SonarQube server
248 such as SonarCloud.io. Optionally runs a shell script before tox.
250 Requires ``SonarQube Scanner for Jenkins``
252 This job runs on the master branch because the basic Sonar configuration
253 does not support multi-branch.
255 Plug-in configurations
256 Manage Jenkins --> Configure System --> SonarQube servers
257 - Name: Sonar (fixed)
258 - Server URL: https://sonar.project.org/ or https://sonarcloud.io
259 - Server authentication token: none for local, API token (saved as
260 a "secret text" credential) for Sonarcloud
262 Manage Jenkins --> Global Tool Configuration --> SonarQube Scanner
263 - Name: SonarQube Scanner (fixed)
264 - Install automatically
265 - Select latest version
269 - {project-name}-tox-sonarqube
270 - gerrit-tox-sonarqube
271 - github-tox-sonarqube
273 :Comment Trigger: ``run-sonar``
275 :Required parameters:
277 :build-node: The node to run the build on.
278 (Commonly in defaults.yaml)
279 :jenkins-ssh-credential: Credential to use for SSH.
280 (Commonly in defaults.yaml)
281 :project: The git repository name.
282 :project-name: Prefix used to name jobs.
284 .. comment Start ignoring WriteGoodLintBear
286 :Optional Parameters:
288 :archive-artifacts: Pattern for files to archive to the logs server
289 (default: '\*\*/\*.log')
290 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
291 :build-timeout: Timeout in minutes before aborting build. (default: 15)
292 :cron: Cron schedule when to trigger the job. This parameter also
293 supports multiline input via YAML pipe | character in cases where
294 one may want to provide more than 1 cron timer. (default: @weekly)
295 :disable-job: Whether to disable the job (default: false)
296 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
297 :github-url: URL for Github. (default: https://github.com)
298 :parallel: Boolean indicator for tox to run tests in parallel or series.
299 (default: false, in series)
300 :pre-build-script: Shell script to run before tox. Useful for setting up
301 dependencies. (default: a string with a shell comment)
302 :python-version: Python version to invoke pip install of tox-pyenv
304 :sonar-additional-args: Command line arguments. (default: '')
305 :sonar-java-opts: JVM options. For example, use option -Xmx
306 to increase the memory size limit. (default: '')
307 :sonar-project-file: The file name with Sonar configuration properties
308 (default: sonar-project.properties)
309 :sonar-properties: Sonar configuration properties. (default: '')
310 :sonar-task: Sonar task to run. (default: '')
311 :tox-dir: Directory containing the project's tox.ini relative to
312 the workspace. The default uses tox.ini at the project root.
314 :tox-envs: Tox environments to run. If blank run everything described
315 in tox.ini. (default: '')
317 .. comment Stop ignoring
319 .. note:: A job definition must provide one of the optional parameters
320 ``sonar-project-file`` and ``sonar-properties``; they cannot both be
321 empty. Set Sonar properties directly in the job definition by setting
322 the ``sonar-project-file`` property to ``""`` and adding all properties
323 under ``sonar-properties``.
325 :Required Sonar Properties:
327 - sonar.login: The API token for authentication at SonarCloud.
328 Commonly defined as key "sonarcloud_api_token" in defaults.yaml.
329 - sonar.organization: The umbrella project name; e.g., "opendaylight".
330 Commonly defined as key "sonarcloud_project_organization" in defaults.yaml.
331 - sonar.projectName: The git repository name without slashes; e.g., "infrautils".
332 - sonar.projectKey: The globally unique key for the report in SonarCloud. Most
333 teams use the catenation of sonar.organization, an underscore, and
334 sonar.projectName; e.g., "opendaylight_infrautils".
336 :Optional Sonar Properties:
338 - sonar.cfamily.gcov.reportsPath: directory with GCOV output files
339 - Documentation of SonarQube properties is here:
340 https://docs.sonarqube.org/latest/analysis/overview/
343 Example job definition
344 ^^^^^^^^^^^^^^^^^^^^^^
346 The following example defines a job for a basic Python project. This definition
347 uses configuration parameters in the umbrella project's defaults.yaml file.
352 name: my-package-sonar
354 project-name: my-package
355 sonar-project-file: ""
357 sonar.login={sonarcloud_api_token}
358 sonar.projectKey={sonarcloud_project_organization}_{project-name}
359 sonar.projectName={project-name}
360 sonar.organization={sonarcloud_project_organization}
361 sonar.sourceEncoding=UTF-8
362 sonar.sources=mypackage
363 sonar.exclusions=tests/*,setup.py
364 sonar.python.coverage.reportPaths=coverage.xml
366 - gerrit-tox-sonarqube
372 Tox runner to verify a project on creation of a patch set. This job
373 is pyenv aware so if the image contains an installation of pyenv at
374 /opt/pyenv it will pick it up and run Python tests with the
375 appropriate Python versions. This job will set the following pyenv
376 variables before running.
380 export PYENV_ROOT="/opt/pyenv"
381 export PATH="$PYENV_ROOT/bin:$PATH"
385 - {project-name}-tox-verify-{stream}
389 :Comment Trigger: **recheck|reverify** post a comment with one of the
390 triggers to launch this job manually. Do not include any other
391 text or vote in the same comment.
393 :Required Parameters:
395 :build-node: The node to run build on.
396 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
399 :Optional Parameters:
401 :branch: The branch to build against. (default: master)
402 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
403 :build-timeout: Timeout in minutes before aborting build. (default: 10)
404 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
405 :pre-build-script: Shell script to execute before the Tox builder.
406 For example, install prerequisites or move files to the repo root.
407 (default: a string with a shell comment)
408 :parallel: Boolean indicator for tox to run tests in parallel or series.
409 (default: false, in series)
410 :python-version: Python version to invoke pip install of tox-pyenv
412 :stream: Keyword representing a release code-name.
413 Often the same as the branch. (default: master)
414 :submodule-recursive: Whether to checkout submodules recursively.
416 :submodule-timeout: Timeout (in minutes) for checkout operation.
418 :submodule-disable: Disable submodule checkout operation.
420 :tox-dir: Directory containing the project's tox.ini relative to
421 the workspace. The default uses tox.ini at the project root.
423 :tox-envs: Tox environments to run. If blank run everything described
424 in tox.ini. (default: '')
425 :gerrit_trigger_file_paths: Override file paths used to filter which file
426 modifications trigger a build. Refer to JJB documentation for "file-path" details.
427 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
433 Tox runner to verify a project after merge of a patch set. This job
434 is pyenv aware so if the image contains an installation of pyenv at
435 /opt/pyenv it will pick it up and run Python tests with the
436 appropriate Python versions. This job will set the following pyenv
437 variables before running.
441 export PYENV_ROOT="/opt/pyenv"
442 export PATH="$PYENV_ROOT/bin:$PATH"
446 - {project-name}-tox-merge-{stream}
450 :Comment Trigger: **remerge** post a comment with the trigger to launch
451 this job manually. Do not include any other text or vote in the
454 :Required Parameters:
456 :build-node: The node to run build on.
457 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
460 :Optional Parameters:
462 :branch: The branch to build against. (default: master)
463 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
464 :build-timeout: Timeout in minutes before aborting build. (default: 10)
465 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
466 :pre-build-script: Shell script to execute before the CLM builder.
467 For example, install prerequisites or move files to the repo root.
468 (default: a string with a shell comment)
469 :python-version: Python version to invoke pip install of tox-pyenv
471 :stream: Keyword representing a release code-name.
472 Often the same as the branch. (default: master)
473 :submodule-recursive: Whether to checkout submodules recursively.
475 :submodule-timeout: Timeout (in minutes) for checkout operation.
477 :submodule-disable: Disable submodule checkout operation.
479 :tox-dir: Directory containing the project's tox.ini relative to
480 the workspace. The default uses tox.ini at the project root.
482 :tox-envs: Tox environments to run. If blank run everything described
483 in tox.ini. (default: '')
484 :gerrit_trigger_file_paths: Override file paths used to filter which file
485 modifications trigger a build. Refer to JJB documentation for "file-path" details.
486 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
492 Creates and uploads package distribution files on merge of a patch set.
493 Runs tox, builds a source distribution and (optionally) a binary
494 distribution, and uploads the distribution(s) to a PyPI repository.
495 The project git repository must have a setup.py file
496 with configuration for packaging the component.
498 Projects can choose **either** this template to publish on merge,
499 **or** the Stage template to publish on command.
501 This job should use a staging repository like testpypi.python.org,
502 which sets up use of release jobs to promote the distributions later.
503 This job can also use a public release area like the global PyPI
504 repository if the release process is not needed. These PyPI
505 repositories allow upload of a package at a specific version once,
506 they do not allow overwrite of a package. This means that a merge job
507 will fail in the upload step if the package version already exists in
508 the target repository.
510 The tox runner is pyenv aware so if the image contains an installation
511 of pyenv at /opt/pyenv it will pick it up and run Python tests with
512 the appropriate Python versions. The tox runner sets the following
513 pyenv variables before running.
517 export PYENV_ROOT="/opt/pyenv"
518 export PATH="$PYENV_ROOT/bin:$PATH"
520 See the recommended directory layout documented in the PyPI Verify job.
522 Jobs using this PyPI template depend on a .pypirc configuration file
523 in the Jenkins builder home directory. An example appears next that uses
524 API tokens. Note that in the [pypi] entry the repository key-value pair
525 is optional, it defaults to pypi.org.
529 [distutils] # this tells distutils what package indexes you can push to
530 index-servers = pypi-test pypi
533 repository: https://test.pypi.org/legacy/
535 password: pypi-test-api-token-goes-here
539 password: pypi-api-token-goes-here
544 - {project-name}-pypi-merge-{stream}
548 :Comment Trigger: **remerge** post a comment with the trigger to launch
549 this job manually. Do not include any other text or vote in the
552 :Required Parameters:
554 :build-node: The node to run the build on.
555 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
557 :mvn-settings: The settings file with credentials for the project
558 :project: Git repository name
559 :project-name: Jenkins job name prefix
561 :Optional Parameters:
563 :branch: The branch to build against. (default: master)
564 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
565 :build-timeout: Timeout in minutes before aborting build. (default: 15)
566 :cron: Cron schedule when to trigger the job. Supports regular builds.
567 Not useful when publishing to pypi.org because that rejects a package
568 if the version exists. (default: empty)
569 :disable-job: Whether to disable the job (default: false)
570 :dist-binary: Whether to build a binary wheel distribution. (default: true)
571 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
572 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
573 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
574 :mvn-version: Version of maven to use. (default: mvn35)
575 :parallel: Boolean indicator for tox to run tests in parallel or series.
576 (default: false, in series)
577 :pre-build-script: Shell script to execute before the tox builder. For
578 example, install system prerequisites. (default: a shell comment)
579 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
580 ideally a server like test.pypi.org. (default: pypi-test)
581 :python-version: Python version to invoke pip install of tox-pyenv
583 :stream: Keyword representing a release code-name.
584 Often the same as the branch. (default: master)
585 :submodule-recursive: Whether to checkout submodules recursively.
587 :submodule-timeout: Timeout (in minutes) for checkout operation.
589 :submodule-disable: Disable submodule checkout operation.
591 :tox-dir: Directory containing the project's tox.ini relative to
592 the workspace. The default uses tox.ini at the project root.
594 :tox-envs: Tox environments to run. If blank run everything described
595 in tox.ini. (default: '')
596 :gerrit_trigger_file_paths: Override file paths used to filter which file
597 modifications trigger a build. Refer to JJB documentation for "file-path" details.
598 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
604 Creates and uploads package distribution files on receipt of a comment.
605 Runs tox, builds a source distribution and (optionally) a binary
606 distribution, and uploads the distribution(s) to a PyPI repository.
607 The project git repository must have a setup.py file with configuration
608 for packaging the component.
610 Projects can choose **either** this template to publish on command,
611 **or** the Merge template to publish on merge.
613 This job should use a staging repository like testpypi.python.org,
614 which sets up use of release jobs to promote the distributions later.
615 This job can also use a public release area like the global PyPI
616 repository if the release process is not needed. These PyPI
617 repositories allow upload of a package at a specific version once,
618 they do not allow overwrite of a package. This means that a job
619 will fail in the upload step if the package version already exists in
620 the target repository.
622 The tox runner is pyenv aware so if the image contains an installation
623 of pyenv at /opt/pyenv it will pick it up and run Python tests with
624 the appropriate Python versions. The tox runner sets the following
625 pyenv variables before running.
629 export PYENV_ROOT="/opt/pyenv"
630 export PATH="$PYENV_ROOT/bin:$PATH"
632 See the recommended directory layout documented in the PyPI Verify job.
634 Jobs using this PyPI template depend on a .pypirc configuration file
635 in the Jenkins builder home directory. An example appears next that uses
636 API tokens. Note that in the [pypi] entry the repository key-value pair
637 is optional, it defaults to pypi.org.
641 [distutils] # this tells distutils what package indexes you can push to
642 index-servers = pypi-test pypi
645 repository: https://test.pypi.org/legacy/
647 password: pypi-test-api-token-goes-here
651 password: pypi-api-token-goes-here
656 - {project-name}-pypi-stage-{stream}
660 :Comment Trigger: **stage-release** post a comment with the trigger to launch
661 this job manually. Do not include any other text or vote in the
664 :Required Parameters:
666 :build-node: The node to run the build on.
667 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
669 :mvn-settings: The settings file with credentials for the project
670 :project: Git repository name
671 :project-name: Jenkins job name prefix
673 :Optional Parameters:
675 :branch: The branch to build against. (default: master)
676 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
677 :build-timeout: Timeout in minutes before aborting build. (default: 15)
678 :cron: Cron schedule when to trigger the job. Supports regular builds.
679 Not useful when publishing to pypi.org because that rejects a package
680 if the version exists. (default: empty)
681 :disable-job: Whether to disable the job (default: false)
682 :dist-binary: Whether to build a binary wheel distribution. (default: true)
683 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
684 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
685 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
686 :mvn-version: Version of maven to use. (default: mvn35)
687 :parallel: Boolean indicator for tox to run tests in parallel or series.
688 (default: false, in series)
689 :pre-build-script: Shell script to execute before the tox builder. For
690 example, install system prerequisites. (default: a shell comment)
691 :pypi-repo: Key for the PyPI target repository in the .pypirc file,
692 ideally a server like test.pypi.org. (default: pypi-test)
693 :python-version: Python version to invoke pip install of tox-pyenv
695 :stream: Keyword representing a release code-name.
696 Often the same as the branch. (default: master)
697 :submodule-recursive: Whether to checkout submodules recursively.
699 :submodule-timeout: Timeout (in minutes) for checkout operation.
701 :submodule-disable: Disable submodule checkout operation.
703 :tox-dir: Directory containing the project's tox.ini relative to
704 the workspace. The default uses tox.ini at the project root.
706 :tox-envs: Tox environments to run. If blank run everything described
707 in tox.ini. (default: '')
708 :gerrit_trigger_file_paths: Override file paths used to filter which file
709 modifications trigger a build. Refer to JJB documentation for "file-path" details.
710 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
715 Verifies a Python library project on creation of a patch set. Runs tox
716 then builds a source distribution and (optionally) a binary
717 distribution. The project repository must have a setup.py file with
718 configuration for packaging the component.
720 Installable package projects should use the directory layout shown
721 below. All Python files are in a repo subdirectory separate from
722 non-Python files like documentation. This layout allows highly
723 specific build-job triggers in Jenkins using the subdirectory
724 paths. For example, a PyPI publisher job should not run on a non-Python
725 file change such as documentation, because the job cannot upload the
728 To make the document files available for building a Python package
729 long description in setup.py, add a symbolic link "docs" in the
730 package subdirectory pointing to the top-level docs directory.
738 │ └── release-notes.rst
740 ├── helloworld-package/
744 │ │ ├── helloworld.py
748 │ │ ├── helloworld_tests.py
749 │ │ └── helloworld_mocks.py
751 │ ├── requirements.txt
756 │ └── pypi-helloworld.yaml
763 The tox runner is pyenv aware so if the image contains an installation
764 of pyenv at /opt/pyenv it will pick it up and run Python tests with
765 the appropriate Python versions. The tox runner sets the following
766 pyenv variables before running.
770 export PYENV_ROOT="/opt/pyenv"
771 export PATH="$PYENV_ROOT/bin:$PATH"
775 - {project-name}-pypi-verify-{stream}
779 :Comment Trigger: **recheck|reverify** post a comment with one of the
780 triggers to launch this job manually. Do not include any other
781 text or vote in the same comment.
783 :Required Parameters:
785 :build-node: The node to run the build on.
786 :jenkins-ssh-credential: Credential to use for SSH. (Generally set
788 :mvn-settings: The settings file with credentials for the project
789 :project: Git repository name
790 :project-name: Jenkins job name prefix
792 :Optional Parameters:
794 :branch: The branch to build against. (default: master)
795 :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
796 :build-timeout: Timeout in minutes before aborting build. (default: 15)
797 :disable-job: Whether to disable the job (default: false)
798 :dist-binary: Whether to build a binary wheel distribution. (default: true)
799 :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
800 :mvn-opts: Sets MAVEN_OPTS to start up the JVM running Maven. (default: '')
801 :mvn-params: Parameters to pass to the mvn CLI. (default: '')
802 :mvn-version: Version of maven to use. (default: mvn35)
803 :parallel: Boolean indicator for tox to run tests in parallel or series.
804 (default: false, in series)
805 :pre-build-script: Shell script to execute before the tox builder. For
806 example, install system prerequisites. (default: a shell comment)
807 :python-version: Python version to invoke pip install of tox-pyenv
809 :stream: Keyword representing a release code-name.
810 Often the same as the branch. (default: master)
811 :submodule-recursive: Whether to checkout submodules recursively.
813 :submodule-timeout: Timeout (in minutes) for checkout operation.
815 :submodule-disable: Disable submodule checkout operation.
817 :tox-dir: Directory containing the project's tox.ini relative to
818 the workspace. The default uses tox.ini at the project root.
820 :tox-envs: Tox environments to run. If blank run everything described
821 in tox.ini. (default: '')
822 :gerrit_trigger_file_paths: Override file paths used to filter which file
823 modifications trigger a build. Refer to JJB documentation for "file-path" details.
824 https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit