Make sure we fail if scripts fail
[releng/global-jjb.git] / README.md
1 # Global JJB
2
3 The purpose of this repository is store generically define reusable JJB
4 templates that can be deployed across LF projects.
5
6 The following variables are necessary to be defined in the Jenkins server as
7 global environment variables as scripts in this repo expect these variables to
8 be available.
9
10 For example:
11
12 ```
13 GIT_URL=ssh://jenkins-$SILO@git.opendaylight.org:29418
14 JENKINS_HOSTNAME=jenkins092
15 LOGS_SERVER=https://logs.opendaylight.org
16 NEXUS_URL=https://nexus.opendaylight.org
17 SILO=releng
18 ```
19
20 ## Jenkins Plugin Requirements
21
22 **Required**
23
24 - Config File Provider
25 - Description Setter
26 - Gerrit Trigger
27 - Post Build Script
28 - SSH Agent
29 - Workspace Cleanup
30
31 **Optional**
32
33 - Mask Passwords
34 - MsgInject
35 - OpenStack Cloud
36 - Timestamps
37
38 ## Installing global-jjb
39
40 global-jjb should be deployed in the ci-management repository's jjb directory as
41 a submodule. global-jjb is versioned and tagged in Gerrit so installing,
42 upgrading, and rolling back changes should be simple via the Gerrit tag system.
43
44 ```
45     # Choose a global-jjb version to install
46     GLOBAL_JJB_VERSION=v0.1.0
47
48     # Add the new submodule to ci-management's jjb directory.
49     # Note: Only needs to be performed once per ci-management repo.
50     cd jjb/
51     git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
52
53     # Checkout the version of global-jjb you wish to deploy.
54     cd global-jjb
55     git checkout $GLOBAL_JJB_VERSION
56
57     # Commit global-jjb version to the ci-management repo.
58     cd ../..
59     git add jjb/global-jjb
60     git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
61
62     # Push the patch to ci-management for review
63     git review
64 ```
65
66 ## Parameters stored in defaults.yaml
67
68 There are a few project specific parameters that should be stored in the
69 ci-management repo's defaults.yaml file.
70
71 **gerrit-server-name**: The name of the Gerrit Server as defined in Gerrit
72 Trigger global configuration.
73
74 **jenkins-ssh-credential**: The name of the Jenkins Credential to use for ssh
75 connections.
76
77 If you are using GitHub then there are two more parameters which
78 will need to be placed in the defaults.yaml
79
80 **github-url**: The URL of GitHub. (Default: https://github.com)
81
82 **github-org**: The name of the GitHub organization.
83
84 defaults.yaml:
85
86 ```
87 - defaults:
88     name: global
89
90     # lf-infra defaults
91     jenkins-ssh-credential: opendaylight-jenkins-ssh
92     gerrit-server-name: OpenDaylight
93     github-org: lfit
94 ```
95
96 ## Config File Management
97
98 ### Logs
99
100 The logs account requires a Maven Settings file created called
101 **jenkins-log-archives-settings** with a server ID of **logs** containing the
102 credentials for the logs user in Nexus.
103
104 ## Deploying ci-jobs
105
106 The CI job group contains multiple jobs that should be deployed in all LF
107 Jenkins infra. The minimal configuration needed to deploy the ci-management
108 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
109 defined in **lf-ci-jobs.yaml**.
110
111 ci-management.yaml:
112
113 ```
114 - project:
115     name: ci-jobs
116
117     jobs:
118       - '{project-name}-ci-jobs'
119
120     project: ci-management
121     project-name: ci-management
122     build-node: centos7-basebuild-2c-1g
123 ```
124
125 Required parameters:
126
127 **project**: is the project repo as defined in Gerrit.
128 **project-name**: is a custom name to call the job in Jenkins.
129 **build-node**: is the name of the builder to use when building (Jenkins label).
130
131 Optional parameters:
132
133 **branch**: is the git branch to build from.
134 **jjb-version**: is the version of JJB to install in the build minion.