docs/jjb/lf-python-jobs.rst

   1 ###########
   2 Python Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 .. include:: ../job-groups.rst
   9
  10 Below is a list of Python job groups:
  11
  12 .. literalinclude:: ../../jjb/lf-python-job-groups.yaml
  13    :language: yaml
  14
  15
  16 Macros
  17 ======
  18
  19 lf-infra-clm-python
  20 -------------------
  21
  22 Runs CLM scanning against a Python project.
  23
  24 :Required Parameters:
  25
  26     :clm-project-name: Project name in Nexus IQ to send results to.
  27
  28 lf-infra-tox-install
  29 --------------------
  30
  31 Installs Tox into a virtualenv.
  32
  33 :Required Parameters:
  34
  35     :python-version: Version of Python to invoke the pip install of the tox-pyenv
  36         package that creates a virtual environment, either "python2" or "python3".
  37
  38 lf-infra-tox-run
  39 ----------------
  40
  41 Creates a Tox virtual environment and invokes tox.
  42
  43 :Required Parameters:
  44
  45     :parallel: Boolean. If true use detox (distributed tox);
  46         else use regular tox.
  47
  48
  49 Job Templates
  50 =============
  51
  52 Python XC CLM
  53 -------------
  54
  55 CLM scans for Python based repos. This job will call the Nexus IQ CLI
  56 directly to run the scans.
  57
  58 A new credential named "nexus-iq-xc-clm" needs to exist in the Jenkins
  59 credentials.  The credential should contain the username and password
  60 to access Nexus IQ Server.
  61
  62 :Template Names:
  63
  64     - {project-name}-python-clm-{stream}
  65     - gerrit-python-xc-clm
  66     - github-python-xc-clm
  67
  68 :Comment Trigger: run-clm
  69
  70 :Required parameters:
  71
  72     :build-node: The node to run build on.
  73     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  74         get configured in defaults.yaml)
  75
  76 :Optional parameters:
  77
  78     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
  79     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use.
  80         (default: 1.44.0-01)
  81     :nexus-iq-namespace: Insert a namespace to project AppID for projects that
  82         share a Nexus IQ system to avoid project name collision. We recommend
  83         inserting a trailing - dash if using this parameter.
  84         For example 'odl-'. (default: '')
  85     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  86     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  87     :java-version: Version of Java to use for the build. (default: openjdk8)
  88     :pre-build-script: Shell script to execute before the CLM builder.
  89         For example, install prerequisites or move files to the repo root.
  90         (default: a string with a shell comment)
  91     :stream: Keyword used to represent a release code-name.
  92         Often the same as the branch. (default: master)
  93     :submodule-recursive: Whether to checkout submodules recursively.
  94         (default: true)
  95     :submodule-timeout: Timeout (in minutes) for checkout operation.
  96         (default: 10)
  97     :submodule-disable: Disable submodule checkout operation.
  98         (default: false)
  99     :gerrit_clm_triggers: Override Gerrit Triggers.
 100     :gerrit_trigger_file_paths: Override file paths used to filter which file
 101         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 102         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 103
 104
 105 Python Sonar with Tox
 106 ---------------------
 107
 108 Sonar scans for Python based repos. This job invokes tox to run tests
 109 and gather coverage statistics from the test results, then invokes
 110 Maven to publish the results to either a Sonar server or SonarCloud.
 111
 112 To get the Sonar coverage results, file tox.ini must exist and contain
 113 coverage commands to run.
 114
 115 The coverage commands define the code that gets executed by the test
 116 suites.  Checking coverage does not guarantee that the tests execute
 117 properly, but it identifies code that is not executed by any test.
 118
 119 .. comment Start ignoring WriteGoodLintBear
 120
 121 This job reuses the Sonar builders used for Java/Maven projects which
 122 run maven twice. The first invocation does nothing for Python
 123 projects, so the job uses the goal 'validate' by default. The second
 124 invocation publishes results using the goal 'sonar:sonar' by default.
 125
 126 .. comment Stop ignoring
 127
 128 For example:
 129
 130 .. code-block:: bash
 131
 132     [testenv:py27]
 133     commands =
 134             coverage run --module pytest --junitxml xunit-results.xml
 135             coverage xml --omit=".tox/py27/*","tests/*"
 136             coverage report --omit=".tox/py27/*","tests/*"
 137
 138 For more details refer to coverage and sonar documentation:
 139
 140 https://coverage.readthedocs.io/
 141
 142 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 143
 144 :Template Names:
 145
 146     - {project-name}-tox-sonar
 147     - gerrit-tox-sonar
 148     - github-tox-sonar
 149
 150 :Comment Trigger: run-sonar
 151
 152 :Required parameters:
 153
 154     :build-node: The node to run build on.
 155     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 156         get configured in defaults.yaml)
 157     :mvn-settings: The name of the settings file with credentials for the project.
 158
 159 .. comment Start ignoring WriteGoodLintBear
 160
 161 :Optional parameters:
 162
 163     :branch: Git branch, should be master (default: master)
 164     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 165     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 166     :cron: Cron schedule when to trigger the job. This parameter also
 167         supports multiline input via YAML pipe | character in cases where
 168         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 169         to run once a day)
 170     :disable-job: Whether to disable the job (default: false)
 171     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 172     :github-url: URL for Github. (default: https://github.com)
 173     :java-version: Version of Java to use for the build. (default: openjdk8)
 174     :mvn-global-settings: The name of the Maven global settings to use
 175     :mvn-goals: The Maven goal to run first. (default: validate)
 176     :mvn-version: Version of maven to use. (default: mvn35)
 177     :parallel: Boolean indicator for tox to run tests in parallel or series.
 178         (default: false, in series)
 179     :pre-build-script: Shell script to execute before the Sonar builder.
 180         For example, install prerequisites or move files to the repo root.
 181         (default: a string with a shell comment)
 182     :python-version: Python version to invoke pip install of tox-pyenv
 183         (default: python2)
 184     :sonarcloud: Boolean indicator to use SonarCloud ``true|false``.
 185         (default: false)
 186     :sonarcloud-project-key: SonarCloud project key. (default: '')
 187     :sonarcloud-project-organization: SonarCloud project organization.
 188         (default: '')
 189     :sonarcloud-api-token: SonarCloud API Token. (default: '')
 190     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 191     :stream: Keyword used to represent a release code-name.
 192         Often the same as the branch. (default: master)
 193     :submodule-recursive: Whether to checkout submodules recursively.
 194         (default: true)
 195     :submodule-timeout: Timeout (in minutes) for checkout operation.
 196         (default: 10)
 197     :submodule-disable: Disable submodule checkout operation.
 198         (default: false)
 199     :tox-dir: Directory containing the project's tox.ini relative to
 200         the workspace. The default uses tox.ini at the project root.
 201         (default: '.')
 202     :tox-envs: Tox environments to run. If blank run everything described
 203         in tox.ini. (default: '')
 204     :gerrit_sonar_triggers: Override Gerrit Triggers.
 205     :gerrit_trigger_file_paths: Override file paths used to filter which file
 206         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 207         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 208
 209 .. comment Stop ignoring
 210
 211
 212 Tox Verify
 213 ----------
 214
 215 Tox runner to verify a project on creation of a patch set.  This job
 216 is pyenv aware so if the image contains an installation of pyenv at
 217 /opt/pyenv it will pick it up and run Python tests with the
 218 appropriate Python versions. This job will set the following pyenv
 219 variables before running.
 220
 221 .. code:: bash
 222
 223    export PYENV_ROOT="/opt/pyenv"
 224    export PATH="$PYENV_ROOT/bin:$PATH"
 225
 226 :Template Names:
 227
 228     - {project-name}-tox-verify-{stream}
 229     - gerrit-tox-verify
 230     - github-tox-verify
 231
 232 :Comment Trigger: recheck|reverify
 233
 234 :Required Parameters:
 235
 236     :build-node: The node to run build on.
 237     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 238         in defaults.yaml)
 239
 240 :Optional Parameters:
 241
 242     :branch: The branch to build against. (default: master)
 243     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 244     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 245     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 246     :pre-build-script: Shell script to execute before the Tox builder.
 247         For example, install prerequisites or move files to the repo root.
 248         (default: a string with a shell comment)
 249     :parallel: Boolean indicator for tox to run tests in parallel or series.
 250        (default: false, in series)
 251     :python-version: Python version to invoke pip install of tox-pyenv
 252         (default: python2)
 253     :stream: Keyword representing a release code-name.
 254         Often the same as the branch. (default: master)
 255     :submodule-recursive: Whether to checkout submodules recursively.
 256         (default: true)
 257     :submodule-timeout: Timeout (in minutes) for checkout operation.
 258         (default: 10)
 259     :submodule-disable: Disable submodule checkout operation.
 260         (default: false)
 261     :tox-dir: Directory containing the project's tox.ini relative to
 262         the workspace. The default uses tox.ini at the project root.
 263         (default: '.')
 264     :tox-envs: Tox environments to run. If blank run everything described
 265         in tox.ini. (default: '')
 266     :gerrit_trigger_file_paths: Override file paths used to filter which file
 267         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 268         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 269
 270
 271 Tox Merge
 272 ---------
 273
 274 Tox runner to verify a project after merge of a patch set.  This job
 275 is pyenv aware so if the image contains an installation of pyenv at
 276 /opt/pyenv it will pick it up and run Python tests with the
 277 appropriate Python versions. This job will set the following pyenv
 278 variables before running.
 279
 280 .. code:: bash
 281
 282    export PYENV_ROOT="/opt/pyenv"
 283    export PATH="$PYENV_ROOT/bin:$PATH"
 284
 285 :Template Names:
 286
 287     - {project-name}-tox-merge-{stream}
 288     - gerrit-tox-merge
 289     - github-tox-merge
 290
 291 :Comment Trigger: remerge
 292
 293 :Required Parameters:
 294
 295     :build-node: The node to run build on.
 296     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 297         in defaults.yaml)
 298
 299 :Optional Parameters:
 300
 301     :branch: The branch to build against. (default: master)
 302     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 303     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 304     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 305     :pre-build-script: Shell script to execute before the CLM builder.
 306         For example, install prerequisites or move files to the repo root.
 307         (default: a string with a shell comment)
 308     :python-version: Python version to invoke pip install of tox-pyenv
 309         (default: python2)
 310     :stream: Keyword representing a release code-name.
 311         Often the same as the branch. (default: master)
 312     :submodule-recursive: Whether to checkout submodules recursively.
 313         (default: true)
 314     :submodule-timeout: Timeout (in minutes) for checkout operation.
 315         (default: 10)
 316     :submodule-disable: Disable submodule checkout operation.
 317         (default: false)
 318     :tox-dir: Directory containing the project's tox.ini relative to
 319         the workspace. The default uses tox.ini at the project root.
 320         (default: '.')
 321     :tox-envs: Tox environments to run. If blank run everything described
 322         in tox.ini. (default: '')
 323     :gerrit_trigger_file_paths: Override file paths used to filter which file
 324         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 325         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 326
 327
 328 PyPI Verify
 329 -----------
 330
 331 Verifies a Python library project on creation of a patch set. Runs tox
 332 then builds a source distribution and (optionally) a binary
 333 distribution. The project repository must have a setup.py file with
 334 configuration for packaging the component.
 335
 336 The tox runner is pyenv aware so if the image contains an installation
 337 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 338 the appropriate Python versions. The tox runner sets the following
 339 pyenv variables before running.
 340
 341 .. code:: bash
 342
 343    export PYENV_ROOT="/opt/pyenv"
 344    export PATH="$PYENV_ROOT/bin:$PATH"
 345
 346 :Template Names:
 347
 348     - {project-name}-pypi-verify-{stream}
 349     - gerrit-pypi-verify
 350     - github-pypi-verify
 351
 352 :Comment Trigger: recheck
 353
 354 :Required Parameters:
 355
 356     :build-node: The node to run the build on.
 357     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 358         in defaults.yaml)
 359     :project: Git repository name
 360     :project-name: Jenkins job name prefix
 361
 362 :Optional Parameters:
 363
 364     :branch: The branch to build against. (default: master)
 365     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 366     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 367     :disable-job: Whether to disable the job (default: false)
 368     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 369     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 370     :parallel: Boolean indicator for tox to run tests in parallel or series.
 371        (default: false, in series)
 372     :pre-build-script: Shell script to execute before the tox builder. For
 373         example, install system prerequisites. (default: a shell comment)
 374     :python-version: Python version to invoke pip install of tox-pyenv
 375         (default: python3)
 376     :stream: Keyword representing a release code-name.
 377         Often the same as the branch. (default: master)
 378     :submodule-recursive: Whether to checkout submodules recursively.
 379         (default: true)
 380     :submodule-timeout: Timeout (in minutes) for checkout operation.
 381         (default: 10)
 382     :submodule-disable: Disable submodule checkout operation.
 383         (default: false)
 384     :tox-dir: Directory containing the project's tox.ini relative to
 385         the workspace. The default uses tox.ini at the project root.
 386         (default: '.')
 387     :tox-envs: Tox environments to run. If blank run everything described
 388         in tox.ini. (default: '')
 389     :gerrit_trigger_file_paths: Override file paths used to filter which file
 390         modifications trigger a build. Refer to JJB documentation for "file-path" details.
 391         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 392
 393
 394 PyPI Merge
 395 ----------
 396
 397 Creates and uploads distribution files on merge of a patch set. Runs
 398 tox, builds a source distribution and (optionally) a binary
 399 distribution, and uploads the distribution(s) to a PyPI repository.
 400 This job should use a staging repository like testpypi.python.org,
 401 which sets up use of release jobs to promote the distributions later.
 402 This job can also use a public release area like the global PyPI
 403 repository. The project git repository must have a setup.py file
 404 with configuration for packaging the component.
 405
 406 The tox runner is pyenv aware so if the image contains an installation
 407 of pyenv at /opt/pyenv it will pick it up and run Python tests with
 408 the appropriate Python versions. The tox runner sets the following
 409 pyenv variables before running.
 410
 411 .. code:: bash
 412
 413    export PYENV_ROOT="/opt/pyenv"
 414    export PATH="$PYENV_ROOT/bin:$PATH"
 415
 416
 417 Requires a .pypirc configuration file in the Jenkins builder home directory,
 418 an example appears next that uses API tokens. Note that in the [pypi] entry
 419 the repository key-value pair is optional, it defaults to pypi.org.
 420
 421 .. code-block:: bash
 422
 423     [distutils] # this tells distutils what package indexes you can push to
 424     index-servers = pypi-test pypi
 425
 426     [pypi-test]
 427     repository: https://test.pypi.org/legacy/
 428     username: __token__
 429     password: pypi-test-api-token-goes-here
 430
 431     [pypi]
 432     username: __token__
 433     password: pypi-api-token-goes-here
 434
 435
 436 :Template Names:
 437
 438     - {project-name}-pypi-merge-{stream}
 439     - gerrit-pypi-merge
 440     - github-pypi-merge
 441
 442 :Comment Trigger: remerge
 443
 444 :Required Parameters:
 445
 446     :build-node: The node to run the build on.
 447     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 448         in defaults.yaml)
 449     :project: Git repository name
 450     :project-name: Jenkins job name prefix
 451
 452 :Optional Parameters:
 453
 454     :branch: The branch to build against. (default: master)
 455     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 456     :build-timeout: Timeout in minutes before aborting build. (default: 15)
 457     :cron: Cron schedule when to trigger the job. Supports daily builds.
 458         This parameter also supports multiline input via YAML pipe | character in
 459         cases where one may want to provide more than 1 cron timer. (default: empty)
 460     :disable-job: Whether to disable the job (default: false)
 461     :dist-binary: Whether to build a binary wheel distribution. (default: true)
 462     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 463     :parallel: Boolean indicator for tox to run tests in parallel or series.
 464        (default: false, in series)
 465     :pre-build-script: Shell script to execute before the tox builder. For
 466         example, install system prerequisites. (default: a shell comment)
 467     :pypi-repo: Key for the PyPI target repository in the .pypirc file,
 468         ideally a server like test.pypy.org. (default: pypi-test)
 469     :python-version: Python version to invoke pip install of tox-pyenv
 470         (default: python3)
 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.
 474         (default: true)
 475     :submodule-timeout: Timeout (in minutes) for checkout operation.
 476         (default: 10)
 477     :submodule-disable: Disable submodule checkout operation.
 478         (default: false)
 479     :tox-dir: Directory containing the project's tox.ini relative to
 480         the workspace. The default uses tox.ini at the project root.
 481         (default: '.')
 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