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