docs/jjb/lf-python-jobs.rst

   1 ###########
   2 Python Jobs
   3 ###########
   4
   5 Job Groups
   6 ==========
   7
   8 {project-name}-python-jobs
   9 --------------------------
  10
  11 Jobs for Python projects using Gerrit.
  12
  13 :Includes:
  14
  15     - gerrit-tox-verify
  16
  17 {project-name}-github-python-jobs
  18 ---------------------------------
  19
  20 Jobs for Python projects using GitHub.
  21
  22 :Includes:
  23
  24     - github-tox-verify
  25
  26
  27 Macros
  28 ======
  29
  30 lf-infra-clm-python
  31 -------------------
  32
  33 Run CLM scanning against a Python project.
  34
  35 :Required Parameters:
  36
  37     :clm-project-name: Project name in Nexus IQ to send results to.
  38
  39 lf-infra-tox-install
  40 --------------------
  41
  42 Install Tox into a virtualenv.
  43
  44 :Required Parameters:
  45
  46     :python-version: Version of Python to install into the Tox virtualenv.
  47         Eg. python2 / python3
  48
  49 lf-infra-tox-sonar
  50 ------------------
  51
  52 Runs Sonar scanning against a Python project.
  53
  54 :Required Parameters:
  55
  56     :java-version: Version of Java to use to run Sonar.
  57     :mvn-version: Version of Maven to use to run Sonar.
  58
  59 lf-tox-install
  60 --------------
  61
  62 Runs a shell script that installs tox in a Python virtualenv.
  63
  64 :Required Parameters:
  65
  66     :python-version: Base Python version to use in the virtualenv. For example
  67         python2 or python3.
  68
  69
  70 Job Templates
  71 =============
  72
  73 Python XC CLM
  74 -------------
  75
  76 CLM scans for Python based repos. This job will call the Nexus IQ CLI
  77 directly to run the scans.
  78
  79 A new credential named "nexus-iq-xc-clm" needs to exist in the Jenkins credentials.
  80 The credential should contain the username and password to access Nexus
  81 IQ Server.
  82
  83 :Template Names:
  84
  85     - {project-name}-python-clm-{stream}
  86     - gerrit-python-xc-clm
  87     - github-python-xc-clm
  88
  89 :Comment Trigger: run-clm
  90
  91 :Required parameters:
  92
  93     :build-node: The node to run build on.
  94     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
  95         get configured in defaults.yaml)
  96
  97 :Optional parameters:
  98
  99     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 100     :nexus-iq-cli-version: Nexus IQ CLI package version to download and use. (default: 1.44.0-01)
 101     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 102     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 103     :java-version: Version of Java to use for the build. (default: openjdk8)
 104     :stream: Keyword used to represent a release code-name.
 105         Often the same as the branch. (default: master)
 106     :submodule-recursive: Whether to checkout submodules recursively.
 107         (default: true)
 108     :gerrit_clm_triggers: Override Gerrit Triggers.
 109     :gerrit_trigger_file_paths: Override file paths which used to filter which
 110         file modifications will trigger a build. Refer to JJB documentation for
 111         "file-path" details.
 112         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 113
 114
 115 Python Sonar with Tox
 116 ---------------------
 117
 118 Sonar scans for Python based repos. This job will perform a tox call which
 119 runs the coverage command to gather tests results. These test results get
 120 published back into Sonar after running the Sonar goals.
 121
 122 To get the Sonar coverage results, tox.ini needs to exist and configured
 123 with coverage commands to run.
 124
 125 The coverage commands define the code that gets executed by the test suites.
 126 It does not guarantee that the code tests executed properly, but it will help
 127 pointing out the code that is not tested at all.
 128
 129 For example:
 130
 131 .. code-block:: bash
 132
 133     [testenv:py27]
 134     commands =
 135             coverage run --module pytest --junitxml xunit-results.xml
 136             coverage xml --omit=".tox/py27/*","tests/*"
 137             coverage report --omit=".tox/py27/*","tests/*"
 138
 139 For more details refer to coverage and sonar documentation:
 140
 141 https://coverage.readthedocs.io/
 142
 143 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 144
 145 :Template Names:
 146
 147     - {project-name}-tox-sonar
 148     - gerrit-tox-sonar
 149     - github-tox-sonar
 150
 151 :Comment Trigger: run-sonar
 152
 153 :Required parameters:
 154
 155     :build-node: The node to run build on.
 156     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 157         get configured in defaults.yaml)
 158     :mvn-settings: The name of settings file containing credentials for the project.
 159
 160 :Optional parameters:
 161
 162     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 163     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 164     :cron: Cron schedule when to trigger the job. This parameter also
 165         supports multiline input via YAML pipe | character in cases where
 166         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 167         to run once a day)
 168     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 169     :java-version: Version of Java to use for the build. (default: openjdk8)
 170     :mvn-global-settings: The name of the Maven global settings to use for
 171         Maven configuration. (default: global-settings)
 172     :mvn-version: Version of maven to use. (default: mvn35)
 173     :stream: Keyword used to represent a release code-name.
 174         Often the same as the branch. (default: master)
 175     :submodule-recursive: Whether to checkout submodules recursively.
 176         (default: true)
 177     :gerrit_sonar_triggers: Override Gerrit Triggers.
 178     :gerrit_trigger_file_paths: Override file paths which used to filter which
 179         file modifications will trigger a build. Refer to JJB documentation for
 180         "file-path" details.
 181         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 182
 183
 184 Tox Verify
 185 ----------
 186
 187 Tox runner to verify a project. This job is pyenv aware so if the image
 188 contains an installation of pyenv at /opt/pyenv it will pick it up and run
 189 Python tests with the appropriate Python versions. This job will set the
 190 following pyenv variables before running.
 191
 192 .. code:: bash
 193
 194    export PYENV_ROOT="/opt/pyenv"
 195    export PATH="$PYENV_ROOT/bin:$PATH"
 196
 197 :Template Names:
 198
 199     - {project-name}-tox-verify-{stream}
 200     - gerrit-tox-verify
 201     - github-tox-verify
 202
 203 :Comment Trigger: recheck|reverify
 204
 205 :Required Parameters:
 206
 207     :build-node: The node to run build on.
 208     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 209         in defaults.yaml)
 210
 211 :Optional Parameters:
 212
 213     :branch: The branch to build against. (default: master)
 214     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 215     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 216     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 217     :python-version: Version of Python to configure as a base in virtualenv.
 218         (default: python3)
 219     :stream: Keyword representing a release code-name.
 220         Often the same as the branch. (default: master)
 221     :submodule-recursive: Whether to checkout submodules recursively.
 222         (default: true)
 223     :tox-dir: Directory containing the project's tox.ini relative to
 224         the workspace. Empty works if tox.ini is at project root.
 225         (default: '')
 226     :tox-envs: Tox environments to run. If blank run everything described
 227         in tox.ini. (default: '')
 228     :gerrit_trigger_file_paths: Override file paths which used to filter which
 229         file modifications will trigger a build. Refer to JJB documentation for
 230         "file-path" details.
 231         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit