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. (default: 1.44.0-01)
  90     :build-timeout: Timeout in minutes before aborting build. (default: 60)
  91     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
  92     :java-version: Version of Java to use for the build. (default: openjdk8)
  93     :stream: Keyword used to represent a release code-name.
  94         Often the same as the branch. (default: master)
  95     :submodule-recursive: Whether to checkout submodules recursively.
  96         (default: true)
  97     :gerrit_clm_triggers: Override Gerrit Triggers.
  98     :gerrit_trigger_file_paths: Override file paths which used to filter which
  99         file modifications will trigger a build. Refer to JJB documentation for
 100         "file-path" details.
 101         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 102
 103
 104 Python Sonar with Tox
 105 ---------------------
 106
 107 Sonar scans for Python based repos. This job will perform a tox call which
 108 runs the coverage command to gather tests results. These test results get
 109 published back into Sonar after running the Sonar goals.
 110
 111 To get the Sonar coverage results, tox.ini needs to exist and configured
 112 with coverage commands to run.
 113
 114 The coverage commands define the code that gets executed by the test suites.
 115 It does not guarantee that the code tests executed properly, but it will help
 116 pointing out the code that is not tested at all.
 117
 118 For example:
 119
 120 .. code-block:: bash
 121
 122     [testenv:py27]
 123     commands =
 124             coverage run --module pytest --junitxml xunit-results.xml
 125             coverage xml --omit=".tox/py27/*","tests/*"
 126             coverage report --omit=".tox/py27/*","tests/*"
 127
 128 For more details refer to coverage and sonar documentation:
 129
 130 https://coverage.readthedocs.io/
 131
 132 https://docs.sonarqube.org/display/PLUG/Python+Coverage+Results+Import
 133
 134 :Template Names:
 135
 136     - {project-name}-tox-sonar
 137     - gerrit-tox-sonar
 138     - github-tox-sonar
 139
 140 :Comment Trigger: run-sonar
 141
 142 :Required parameters:
 143
 144     :build-node: The node to run build on.
 145     :jenkins-ssh-credential: Credential to use for SSH. (Generally should
 146         get configured in defaults.yaml)
 147     :mvn-settings: The name of settings file containing credentials for the project.
 148
 149 :Optional parameters:
 150
 151     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 152     :build-timeout: Timeout in minutes before aborting build. (default: 60)
 153     :cron: Cron schedule when to trigger the job. This parameter also
 154         supports multiline input via YAML pipe | character in cases where
 155         one may want to provide more than 1 cron timer.  (default: H 11 * * *
 156         to run once a day)
 157     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 158     :java-version: Version of Java to use for the build. (default: openjdk8)
 159     :mvn-global-settings: The name of the Maven global settings to use for
 160         Maven configuration. (default: global-settings)
 161     :mvn-version: Version of maven to use. (default: mvn35)
 162     :stream: Keyword used to represent a release code-name.
 163         Often the same as the branch. (default: master)
 164     :submodule-recursive: Whether to checkout submodules recursively.
 165         (default: true)
 166     :gerrit_sonar_triggers: Override Gerrit Triggers.
 167     :gerrit_trigger_file_paths: Override file paths which used to filter which
 168         file modifications will trigger a build. Refer to JJB documentation for
 169         "file-path" details.
 170         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit
 171
 172
 173 Tox Verify
 174 ----------
 175
 176 Tox runner to verify a project. This job is pyenv aware so if the image
 177 contains an installation of pyenv at /opt/pyenv it will pick it up and run
 178 Python tests with the appropriate Python versions. This job will set the
 179 following pyenv variables before running.
 180
 181 .. code:: bash
 182
 183    export PYENV_ROOT="/opt/pyenv"
 184    export PATH="$PYENV_ROOT/bin:$PATH"
 185
 186 :Template Names:
 187
 188     - {project-name}-tox-verify-{stream}
 189     - gerrit-tox-verify
 190     - github-tox-verify
 191
 192 :Comment Trigger: recheck|reverify
 193
 194 :Required Parameters:
 195
 196     :build-node: The node to run build on.
 197     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
 198         in defaults.yaml)
 199
 200 :Optional Parameters:
 201
 202     :branch: The branch to build against. (default: master)
 203     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
 204     :build-timeout: Timeout in minutes before aborting build. (default: 10)
 205     :git-url: URL clone project from. (default: $GIT_URL/$PROJECT)
 206     :python-version: Version of Python to configure as a base in virtualenv.
 207         (default: python3)
 208     :stream: Keyword representing a release code-name.
 209         Often the same as the branch. (default: master)
 210     :submodule-recursive: Whether to checkout submodules recursively.
 211         (default: true)
 212     :tox-dir: Directory containing the project's tox.ini relative to
 213         the workspace. Empty works if tox.ini is at project root.
 214         (default: '')
 215     :tox-envs: Tox environments to run. If blank run everything described
 216         in tox.ini. (default: '')
 217     :gerrit_trigger_file_paths: Override file paths which used to filter which
 218         file modifications will trigger a build. Refer to JJB documentation for
 219         "file-path" details.
 220         https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit