3 The purpose of this repository is store generically defined, reusable JJB
4 templates, deployable across LF projects.
6 Define the following variables in the Jenkins server as
7 global environment variables as scripts in this repo expect these variables to
13 GERRIT_URL=https://git.opendaylight.org/gerrit
14 GIT_URL=ssh://jenkins-$SILO@git.opendaylight.org:29418
15 GIT_CLONE_URL=git@github.com:
16 JENKINS_HOSTNAME=jenkins092
17 LOGS_SERVER=https://logs.opendaylight.org
18 NEXUS_URL=https://nexus.opendaylight.org
20 SONAR_URL=https://sonar.opendaylight.org
23 Note: Use **GIT_CLONE_URL** for GitHub projects as this
24 will be different from the URL used the poperties
27 ## Jenkins Plugin Requirements
31 - [Config File Provider](https://plugins.jenkins.io/config-file-provider)
32 - [Description Setter](https://plugins.jenkins.io/description-setter)
33 - [Environment Injector Plugin](https://plugins.jenkins.io/envinject)
34 - [Git plugin](https://plugins.jenkins.io/git)
35 - [Post Build Script](https://plugins.jenkins.io/postbuildscript)
37 Due to security concerns Post Build Script is not available through
38 the Jenkins update center and must install it manually. You can
40 [here](https://updates.jenkins-ci.org/download/plugins/postbuildscript/).
42 - [SSH Agent](https://plugins.jenkins.io/ssh-agent)
43 - [Workspace Cleanup](https://plugins.jenkins.io/ws-cleanup)
45 **Required for Gerrit connected systems**
47 - [Gerrit Trigger](https://plugins.jenkins.io/gerrit-trigger)
49 **Required for GitHub connected systems**
51 - [GitHub plugin](https://plugins.jenkins.io/github)
52 - [GitHub Pull Request Builder](https://plugins.jenkins.io/ghprb)
56 - [Mask Passwords](https://plugins.jenkins.io/mask-passwords)
57 - [MsgInject](https://plugins.jenkins.io/msginject)
58 - [OpenStack Cloud](https://plugins.jenkins.io/openstack-cloud)
59 - [Timestamps](https://plugins.jenkins.io/timestamper)
61 ## Installing global-jjb
63 Deploy global-jjb in the ci-management repository's jjb directory as
64 a submodule. Installing, upgrading, and rolling back changes is simple via the
68 # Choose a global-jjb version to install
69 GLOBAL_JJB_VERSION=v0.1.0
71 # Add the new submodule to ci-management's jjb directory.
72 # Note: Perform once per ci-management repo.
74 git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
76 # Checkout the version of global-jjb you wish to deploy.
78 git checkout $GLOBAL_JJB_VERSION
80 # Commit global-jjb version to the ci-management repo.
82 git add jjb/global-jjb
83 git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
85 # Push the patch to ci-management for review
89 ## Parameters stored in defaults.yaml
91 Configure the following parameters in the ci-management repo's
94 **gerrit-server-name**: The name of the Gerrit Server as defined
95 in Gerrit Trigger global configuration.
97 **jenkins-ssh-credential**: The name of the Jenkins Credential to
98 use for ssh connections.
100 If you are using GitHub then configure the following parameters
103 **git-url**: Set this to the base URL of your GitHub repo. In
104 general this should be <https://github.com>. If you are using
105 GitHub Enterprise, or some other GitHub-style system, then it
106 should be whatever your installation base URL is.
108 **git-clone-url**: This is the clone prefix used by GitHub jobs.
109 Set this to either the same thing as **git-url** or the
110 'git@github.com:' including the trailing ':'
112 **github-org**: The name of the GitHub organization interpolated
115 **github_pr_org**: The name of the GitHub organization. All members
116 of this organization will be able to trigger any job using the
117 `lf-infra-github-pr` macro.
119 **github_pr_whitelist**: List of GitHub members you wish to be able to
120 trigger any job that uses the `lf-infra-github-pr-trigger` macro.
122 **github_pr_admin_list**: List of GitHub members that will have admin
123 privileges on any job using the `lf-infra-github-pr-trigger`
126 **lftools-version**: Version of lftools to install. Can be a specific version
127 like '0.6.1' or a PEP-440 definition. <https://www.python.org/dev/peps/pep-0440/>
128 For example `<1.0.0` or `>=1.0.0,<2.0.0`.
130 **mvn-site-id**: Maven Server ID from settings.xml containing the credentials
131 to push to a Maven site repository.
133 **mvn-staging-id**: Maven Server ID from settings.xml containing the credentials
134 to push to a Maven staging repository.
143 jenkins-ssh-credential: opendaylight-jenkins-ssh
144 gerrit-server-name: OpenDaylight
150 github_pr_admin_list:
152 lftools-version: '<1.0.0'
153 mvn-site-id: opendaylight-site
156 ## Config File Management
160 The logs account requires a Maven Settings file created called
161 **jenkins-log-archives-settings** with a server ID of **logs** containing the
162 credentials for the logs user in Nexus.
166 The CI job group contains jobs that should deploy in all LF
167 Jenkins infra. The minimal configuration needed to deploy the ci-management
168 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
169 defined in **lf-ci-jobs.yaml**.
178 - '{project-name}-ci-jobs'
180 project: ci-management
181 project-name: ci-management
182 build-node: centos7-basebuild-2c-1g
187 **project**: is the project repo as defined in source control.
188 **project-name**: is a custom name to call the job in Jenkins.
189 **build-node**: is the name of the builder to use when building (Jenkins label).
193 **branch**: is the git branch to build from.
194 **jjb-version**: is the version of JJB to install in the build minion.
196 ## Deploying packer-jobs
198 The packer job group contains jobs to build custom minion images. The minimal
199 configuration needed to deploy the packer jobs is as follows which deploys the
200 **{project-name}-packer-jobs** job group as defined in **lf-ci-jobs.yaml**.
209 - '{project-name}-packer-jobs'
211 project: ci-management
212 project-name: ci-management
214 build-node: centos7-basebuild-2c-1g
237 **project**: is the project repo as defined in source control.
238 **project-name**: is a custom name to call the job in Jenkins.
239 **build-node**: is the name of the builder to use when building (Jenkins label).
240 **platforms**: is a list of supported platforms.
241 **templates**: is a list of supported templates.
245 **branch**: is the git branch to build from.
246 **packer-version**: is the version of packer to install in the build minion,
247 when packer is not available.
248 **exclude**: is a combination of platforms and templates which are not required
251 ## Deploying Python jobs
253 We provide the following Python jobs templates:
255 ### {project-name}-tox-verify-{stream}
257 Use this job to call python-tox to run builds and tests. The most common
258 usage of this job is to run the Coala linter against projects.
264 - '{project-name}-tox-verify-{stream}'
266 project-name: builder
267 project: releng/builder
268 build-node: centos7-java-builder-2c-4g
274 **project**: is the project repo as defined in source control.
275 **project-name**: is a custom name to call the job in Jenkins.
276 **build-node**: is the name of the builder to use when building (Jenkins label).
277 **stream**: typically `master` or matching the build branch. This
278 is a useful keywords to map a release codename to a branch. For
279 example OpenDaylight uses this to map stream=carbon to
280 branch=stable/carbon.
284 **branch**: is the git branch to build from.
285 **jjb-version**: is the version of JJB to install in the build minion.
286 **tox-dir**: directory containing tox.ini file (default: '')
287 **tox-envs**: tox environments to run (default: '')
289 ## Archiving logs in Jobs
291 There are 2 ways supported for archiving log information:
293 1) Job creates $WORKSPACE/archives directory and places logs there
295 This method pushes the entire archives directory to the log server
296 in the same structure as configured in the archives directory.
298 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
300 In this method a job can define a globstar for example `**/*.log` which then
301 causes the archive script to do a globstar search for that pattern and archives
302 any files it finds matching.
304 ## Overriding merge and verify triggers
306 The default trigger conditions for Merge and Verify job types are overrideable
307 in a project configuration by overriding the following variables:
309 - gerrit_merge_triggers
310 - gerrit_verify_triggers
312 These variables take a list of trigger-on values as defined in JJB docs here:
313 <https://docs.openstack.org/infra/jenkins-job-builder/triggers.html#triggers.gerrit>
319 When using ShellCheck to lint global-jjb or any projects that include
320 global-jjb as part of their project (common with ci-management repos) then
321 we require version 0.4.x of ShellCheck installed on the build vms. This version
322 introduces annotations used by shell scripts in this repo.