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