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