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 Maven 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 Run 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 Install Tox into a virtualenv.
  32
  33 :Required Parameters:
  34
  35     :python-version: Version of Python to install into the Tox virtualenv.
  36         Eg. python2 / python3
  37
  38 lf-tox-install
  39 --------------
  40
  41 Runs a shell script that installs tox in a Python virtualenv.
  42
  43 :Required Parameters:
  44
  45     :python-version: Base Python version to use in the virtualenv. For example
  46         python2 or python3.
  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 credentials.
  59 The credential should contain the username and password to access Nexus
  60 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 only a 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 which used to filter which
 101         file modifications will trigger a build. Refer to JJB documentation for
 102         "file-path" details.
 103         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 104
 105
 106 Python Sonar with Tox
 107 ---------------------
 108
 109 Sonar scans for Python based repos. This job will invoke tox to run tests
 110 and gather coverage statistics from test results. Then the job invokes Maven
 111 with a Sonar goal, which runs a plugin to publish results to a Sonar server.
 112
 113 To get the Sonar coverage results, tox.ini needs to exist and be configured
 114 with coverage commands to run.
 115
 116 The coverage commands define the code that gets executed by the test suites.
 117 It does not guarantee that the code tests executed properly, but it will help
 118 pointing out the code that is not tested at all.
 119
 120 For example:
 121
 122 .. code-block:: bash
 123
 124     [testenv:py27]
 125     commands =
 126             coverage run --module pytest --junitxml xunit-results.xml
 127             coverage xml --omit=".tox/py27/*","tests/*"
 128             coverage report --omit=".tox/py27/*","tests/*"
 129
 130 For more details refer to coverage and sonar documentation:
 131
 132 https://coverage.readthedocs.io/
 133
 134 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 135
 136 :Template Names:
 137
 138     - {project-name}-tox-sonar
 139     - gerrit-tox-sonar
 140     - github-tox-sonar
 141
 142 :Comment Trigger: run-sonar
 143
 144 :Required parameters:
 145
 146     :build-node: The node to run build on.
 147     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 148         get configured in defaults.yaml)
 149     :mvn-settings: The name of the settings file with credentials for the project.
 150
 151 :Optional parameters:
 152
 153     :branch: Git branch, should be master (default: master)
 154     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 155     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 156     :cron: Cron schedule when to trigger the job. This parameter also
 157         supports multiline input via YAML pipe | character in cases where
 158         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 159         to run once a day)
 160     :disable-job: Whether to disable the job (default: false)
 161     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 162     :github-url: URL for Github. (default: https://github.com)
 163     :java-version: Version of Java to use for the build. (default: openjdk8)
 164     :mvn-global-settings: The name of the Maven global settings to use for
 165     :mvn-goals: The Maven goal to run first. (default: validate)
 166     :mvn-version: Version of maven to use. (default: mvn35)
 167     :pre-build-script: Shell script to execute before the Sonar builder.
 168         For example, install prerequisites or move files to the repo root.
 169         (default: a string with only a comment)
 170     :python-version: Python version (default: python2)
 171     :sonar-mvn-goal: The Maven goal to run the Sonar plugin. (default: sonar:sonar)
 172     :stream: Keyword used to represent a release code-name.
 173         Often the same as the branch. (default: master)
 174     :submodule-recursive: Whether to checkout submodules recursively.
 175         (default: true)
 176     :submodule-timeout: Timeout (in minutes) for checkout operation.
 177         (default: 10)
 178     :submodule-disable: Disable submodule checkout operation.
 179         (default: false)
 180     :gerrit_sonar_triggers: Override Gerrit Triggers.
 181     :gerrit_trigger_file_paths: Override file paths which used to filter which
 182         file modifications will trigger a build. Refer to JJB documentation for
 183         "file-path" details.
 184         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 185
 186
 187 Tox Verify
 188 ----------
 189
 190 Tox runner to verify a project. This job is pyenv aware so if the image
 191 contains an installation of pyenv at /opt/pyenv it will pick it up and run
 192 Python tests with the appropriate Python versions. This job will set the
 193 following pyenv variables before running.
 194
 195 .. code:: bash
 196
 197    export PYENV_ROOT="/opt/pyenv"
 198    export PATH="$PYENV_ROOT/bin:$PATH"
 199
 200 :Template Names:
 201
 202     - {project-name}-tox-verify-{stream}
 203     - gerrit-tox-verify
 204     - github-tox-verify
 205
 206 :Comment Trigger: recheck|reverify
 207
 208 :Required Parameters:
 209
 210     :build-node: The node to run build on.
 211     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 212         in defaults.yaml)
 213
 214 :Optional Parameters:
 215
 216     :branch: The branch to build against. (default: master)
 217     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 218     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 219     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 220     :pre-build-script: Shell script to execute before the Tox builder.
 221         For example, install prerequisites or move files to the repo root.
 222         (default: a string with only a comment)
 223     :python-version: Version of Python to configure as a base in virtualenv.
 224         (default: python3)
 225     :stream: Keyword representing a release code-name.
 226         Often the same as the branch. (default: master)
 227     :submodule-recursive: Whether to checkout submodules recursively.
 228         (default: true)
 229     :submodule-timeout: Timeout (in minutes) for checkout operation.
 230         (default: 10)
 231     :submodule-disable: Disable submodule checkout operation.
 232         (default: false)
 233     :tox-dir: Directory containing the project's tox.ini relative to
 234         the workspace. Empty works if tox.ini is at project root.
 235         (default: '')
 236     :tox-envs: Tox environments to run. If blank run everything described
 237         in tox.ini. (default: '')
 238     :gerrit_trigger_file_paths: Override file paths which used to filter which
 239         file modifications will trigger a build. Refer to JJB documentation for
 240         "file-path" details.
 241         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit