Make sure that jjb-cleanup.sh allows unbound vars
[releng/global-jjb.git] / docs / configuration.rst
1 #############
2 Configuration
3 #############
4
5 .. _defaults-yaml:
6
7 defaults.yaml
8 =============
9
10 This file lives in the ci-management repo typically under the path
11 ``jjb/defaults.yaml``. The purpose of this file is to store default variable
12 values used by global-jjb templates.
13
14 **Required**
15
16 :jenkins-ssh-credential: The name of the Jenkins Credential to
17     use for ssh connections. (ex: jenkins-ssh)
18
19 :lftools-version: Version of lftools to install. Can be a specific version
20     like '0.6.1' or a `PEP-440 definition <https://www.python.org/dev/peps/pep-0440/>`_
21     For example `<1.0.0` or `>=1.0.0,<2.0.0`.
22
23 :mvn-site-id: Maven Server ID from settings.xml containing the credentials
24     to push to a Maven site repository.
25
26 :mvn-staging-id: Maven Server ID from settings.xml containing the credentials
27     to push to a Maven staging repository.
28
29 **Gerrit required parameters**:
30
31 :gerrit-server-name: The name of the Gerrit Server as defined in Gerrit
32     Trigger global configuration. (ex: Primary)
33
34 **GitHub required parameters**:
35
36 :git-url: Set this to the base URL of your GitHub repo. In
37     general this should be https://github.com. If you are using
38     GitHub Enterprise, or some other GitHub-style system, then it
39     should be whatever your installation base URL is.
40
41 :git-clone-url: This is the clone prefix used by GitHub jobs.
42     Set this to either the same thing as **git-url** or the
43     'git@github.com:' including the trailing ':'
44
45 :github-org: The name of the GitHub organization interpolated
46     into the scm config.
47
48 :github_pr_org: The name of the GitHub organization. All members
49     of this organization will be able to trigger jobs.
50
51 :github_pr_whitelist: List of GitHub members you wish to be able to
52     trigger jobs.
53
54 :github_pr_admin_list: List of GitHub members that will have admin
55     privileges on the jobs.
56
57 Example Gerrit Infra:
58
59 .. code-block:: yaml
60
61    - defaults:
62        name: global
63
64        # lf-infra defaults
65        jenkins-ssh-credential: jenkins-ssh
66        gerrit-server-name: OpenDaylight
67        lftools-version: '<1.0.0'
68        mvn-site-id: opendaylight-site
69        mvn-staging-id: opendaylight-staging
70
71 Example GitHub Infra:
72
73 .. code-block:: yaml
74
75    - defaults:
76        name: global
77
78        # lf-infra defaults
79        jenkins-ssh-credential: jenkins-ssh
80        github-org: lfit
81        github_pr_whitelist:
82          - jpwku
83          - tykeal
84          - zxiiro
85        github_pr_admin_list:
86          - tykeal
87        lftools-version: '<1.0.0'
88        mvn-site-id: opendaylight-site
89        mvn-staging-id: opendaylight-staging
90
91 .. _jenkins-files:
92
93 Jenkins Files
94 =============
95
96 global-jjb makes use of the Jenkins Config File Provider plugin to provide some
97 default configurations for certain tools. This section details the files to
98 define in Jenkins' **Manage Files** configuration.
99
100 .. _npmrc:
101
102 npmrc
103 -----
104
105 This file contains default npmrc configuration and lives in $HOME/.npmrc.
106 Documentation for npmrc is available via the `npm project
107 <https://docs.npmjs.com/files/npmrc>`_.
108
109 :Required: This file MUST exist. An empty file is acceptable if a
110     proxy is not available for the project.
111 :type: Custom file
112
113 Create a "Custom file" with contents:
114
115 .. code-block:: ini
116
117    registry = https://nexus.opendaylight.org/content/repositories/npmjs/
118
119 .. _pipconf:
120
121 pipconf
122 -------
123
124 This file contains default configuration for the python-pip tool and lives
125 in $HOME/.config/pip/pip.conf. Documentation for pip.conf is available via the
126 `pip project <https://pip.readthedocs.io/en/stable/user_guide/#configuration>`_.
127
128 :Required: This file MUST exist. An empty file is acceptable if a
129     proxy is not available for the project.
130 :type: Custom file
131
132 Create a "Custom file" with contents:
133
134 .. code-block:: ini
135
136    [global]
137    timeout = 60
138    index-url = https://nexus3.opendaylight.org/repository/PyPi/simple
139
140 .. _jjbini:
141
142 jjbini
143 ------
144
145 This file contains the Jenkins Job Builder `configuration
146 <https://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file>`_
147 for :doc:`jjb/lf-ci-jobs`.
148
149 :Required: This file MUST exist.
150 :type: Custom file
151
152 Create a "Custom file" with contents:
153
154 .. code-block:: ini
155
156     [job_builder]
157     ignore_cache=True
158     keep_descriptions=False
159     include_path=.:scripts:~/git/
160     recursive=True
161
162     [jenkins]
163     user=jenkins-jobbuilder
164     password=1234567890abcdef1234567890abcdef
165     url=https://jenkins.example.org
166     query_plugins_info=False
167
168     [production]
169     user=jenkins-jobbuilder
170     password=1234567890abcdef1234567890abcdef
171     url=https://jenkins.example.org
172     query_plugins_info=False
173
174     [sandbox]
175     user=jenkins-jobbuilder
176     password=1234567890abcdef1234567890abcdef
177     url=https://jenkins.example.org/sandbox
178     query_plugins_info=False
179
180 The last 2 sections are for the ``jenkins-cfg`` job use, they should match the
181 ``silo`` names for the respective Jenkins systems, typically ``production`` and
182 ``sandbox``.
183
184 .. _jenkins-log-archives-settings:
185
186 jenkins-log-archives-settings
187 -----------------------------
188
189 See :ref:`lf-infra-ship-logs` for usage. If not archiving logs then keep this
190 file with default settings, global-jjb needs the file to exist to function.
191
192 Requires a *credential* named 'logs' of type 'Username and Password' created in
193 the Jenkins Credentials system.
194
195 #. Add Server Credentials
196 #. Set ``ServerId`` to ``logs``
197 #. Set ``Credentials`` to the ``logs`` user created in the Credentials System
198
199 :Required: This file MUST exist if using log archiving.
200 :type: Maven settings.xml
201
202 .. code-block:: xml
203
204    <?xml version="1.0" encoding="UTF-8"?>
205    <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
206              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
207              xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
208    </settings>
209
210 .. note::
211
212    This example is the default boilerplate generated by Jenkins with
213    the comments stripped out. We can also use the default generated by Jenkins
214    without modifying it.
215
216 .. _packer-cloud-env:
217
218 packer-cloud-env
219 ----------------
220
221 Cloud environment configuration variables for Packer jobs. These can
222 contain credentials and configuration for whichever clouds packer jobs
223 are using.
224
225 :Required: This file MUST exist to use packer jobs.
226 :type: Json file
227
228 .. code-block:: json
229
230    {
231      "cloud_auth_url": "https://auth.vexxhost.net/v3/",
232      "cloud_tenant": "TENANT_ID",
233      "cloud_user": "CLOUD_USERNAME",
234      "cloud_pass": "CLOUD_PASSWORD",
235      "cloud_network": "CLOUD_NETWORK",
236      "ssh_proxy_host": ""
237    }
238
239 .. _jenkins-ci-jobs:
240
241 Jenkins CI Jobs
242 ===============
243
244 .. _jenkins-cfg-merge:
245
246 jenkins-cfg-merge
247 -----------------
248
249 This job manages Jenkins Global configuration. Refer to
250 the :ref:`CI Documentation <lf-global-jjb-jenkins-cfg-merge>` for job
251 configuration details.
252
253 .. _log-archiving:
254
255 Log Archiving
256 =============
257
258 The logs account requires a Maven Settings file created called
259 **jenkins-log-archives-settings** with a server ID of **logs** containing the
260 credentials for the logs user in Nexus.