Fully render GitHub SCM clone URLs
[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 GIT_CLONE_URL=git@github.com:
15 JENKINS_HOSTNAME=jenkins092
16 LOGS_SERVER=https://logs.opendaylight.org
17 NEXUS_URL=https://nexus.opendaylight.org
18 SILO=releng
19 ```
20 Note: **GIT_CLONE_URL** is only used by Github projects as this
21 will be different from the URL used the poperties
22 configuration.
23
24 ## Jenkins Plugin Requirements
25
26 **Required**
27
28 - Config File Provider
29 - Description Setter
30 - Gerrit Trigger
31 - Post Build Script
32 - SSH Agent
33 - Workspace Cleanup
34
35 **Optional**
36
37 - Mask Passwords
38 - MsgInject
39 - OpenStack Cloud
40 - Timestamps
41
42 ## Installing global-jjb
43
44 global-jjb should be deployed in the ci-management repository's jjb directory as
45 a submodule. global-jjb is versioned and tagged in Gerrit so installing,
46 upgrading, and rolling back changes should be simple via the Gerrit tag system.
47
48 ```
49     # Choose a global-jjb version to install
50     GLOBAL_JJB_VERSION=v0.1.0
51
52     # Add the new submodule to ci-management's jjb directory.
53     # Note: Only needs to be performed once per ci-management repo.
54     cd jjb/
55     git submodule add https://gerrit.linuxfoundation.org/infra/releng/global-jjb
56
57     # Checkout the version of global-jjb you wish to deploy.
58     cd global-jjb
59     git checkout $GLOBAL_JJB_VERSION
60
61     # Commit global-jjb version to the ci-management repo.
62     cd ../..
63     git add jjb/global-jjb
64     git commit -sm "Install global-jjb $GLOBAL_JJB_VERSION"
65
66     # Push the patch to ci-management for review
67     git review
68 ```
69
70 ## Parameters stored in defaults.yaml
71
72 There are a few project specific parameters that should be stored in the
73 ci-management repo's defaults.yaml file.
74
75 **gerrit-server-name**: The name of the Gerrit Server as defined in Gerrit
76 Trigger global configuration.
77
78 **jenkins-ssh-credential**: The name of the Jenkins Credential to use for ssh
79 connections.
80
81 If you are using GitHub then there are two more parameters which
82 will need to be placed in the defaults.yaml
83
84 **git-url**: This should be set to the base URL of your GitHub. In
85 general this should be https://github.com. If you are using GitHub
86 Enterprise, or some other GitHub-style system, then it should be
87 whatever your installation base URL is.
88
89 **git-clone-url**: This is the clone prefix used by GitHub jobs. This
90 should be set to either the same thing as **git-url** or the
91 'git@github.com:' including the trailing ':'
92
93 **github-org**: The name of the GitHub organization.
94
95 defaults.yaml:
96
97 ```
98 - defaults:
99     name: global
100
101     # lf-infra defaults
102     jenkins-ssh-credential: opendaylight-jenkins-ssh
103     gerrit-server-name: OpenDaylight
104     github-org: lfit
105 ```
106
107 ## Config File Management
108
109 ### Logs
110
111 The logs account requires a Maven Settings file created called
112 **jenkins-log-archives-settings** with a server ID of **logs** containing the
113 credentials for the logs user in Nexus.
114
115 ## Deploying ci-jobs
116
117 The CI job group contains multiple jobs that should be deployed in all LF
118 Jenkins infra. The minimal configuration needed to deploy the ci-management
119 jobs is as follows which deploys the **{project-name}-ci-jobs** job group as
120 defined in **lf-ci-jobs.yaml**.
121
122 ci-management.yaml:
123
124 ```
125 - project:
126     name: ci-jobs
127
128     jobs:
129       - '{project-name}-ci-jobs'
130
131     project: ci-management
132     project-name: ci-management
133     build-node: centos7-basebuild-2c-1g
134 ```
135
136 Required parameters:
137
138 **project**: is the project repo as defined in source control.
139 **project-name**: is a custom name to call the job in Jenkins.
140 **build-node**: is the name of the builder to use when building (Jenkins label).
141
142 Optional parameters:
143
144 **branch**: is the git branch to build from.
145 **jjb-version**: is the version of JJB to install in the build minion.
146
147 ## Deploying Python jobs
148
149 We provide the following Python jobs templates:
150
151 ### {project-name}-tox-verify-{stream}
152
153 This job can be used to call python-tox to run builds and tests. The most common
154 usage of this job is to run the Coala linter against projects.
155
156 ```
157 - project:
158     name: builder
159     jobs:
160         - '{project-name}-tox-verify-{stream}'
161
162     project-name: builder
163     project: releng/builder
164     build-node: centos7-java-builder-2c-4g
165     stream: master
166 ```
167
168 Required parameters:
169
170 **project**: is the project repo as defined in source control.
171 **project-name**: is a custom name to call the job in Jenkins.
172 **build-node**: is the name of the builder to use when building (Jenkins label).
173 **stream**: typically `master` or matching whatever branch is being built. This
174             is a useful keywords to map a release codename to a branch. For
175             example OpenDaylight uses this to map stream=carbon to
176             branch=stable/carbon.
177
178 Optional parameters:
179
180 **branch**: is the git branch to build from.
181 **jjb-version**: is the version of JJB to install in the build minion.
182 **tox-dir**: directory containing tox.ini file (default: '')
183 **tox-envs**: tox environments to run (default: '')
184
185 ## Archiving logs in Jobs
186
187 There are 2 ways supported for archiving log information:
188
189 1) Job creates $WORKSPACE/archives directory and places logs there
190
191 In this method the entire archives directory will be pushed to the log server
192 in the same structure as configured in the archives directory.
193
194 2) Via job variable ARCHIVE_ARTIFACTS using globstar patterns.
195
196 In this method a job can define a globstar for example ``**/*.log`` which then
197 causes the archive script to do a globstar search for that pattern and archives
198 any files it finds matching.