1 # ONAP Jenkins Sandbox Process
3 ONAP Jenkins Sandbox provides you Jenkins Job testing/experimentation environment
4 that can be used before pushing job templates to the production
5 [Jenkins](https://jenkins.onap.org).
7 It is configured similar to the ONAP [ci-management] production instance;
8 however, it cannot publish artifacts or vote in Gerrit. Be aware that this is a
9 test environment, and as such there is a limited allotment of minions to test on
10 before pushing code to the ONAP repos.
11 Keep the following points in mind prior to beginning work on ONAP Jenkins Sandbox
14 - Jobs are automatically deleted every weekend
15 - Committers can login and configure Jenkins jobs in the sandbox directly
16 - Sandbox jobs CANNOT perform any upload tasks
17 - Sandbox jobs CANNOT vote on Gerrit
18 - Jenkins nodes are configured using ONAP openstack VMs and you can not access
21 Before you proceed further, ensure you have a Linux Foundation ID (LFID), which is
22 required to access Gerrit & Jenkins. Also, to extend your permissions for uploading
23 Jenkins configurations to Sandbox environment, you must raise a ticket to
24 [Linux Foundation Help Center](https://support.linuxfoundation.org)
26 - [ONAP Jenkins Sandbox Process](#onap-jenkins-sandbox-process)
28 - [Install JJB on your machine](#install-jjb-on-your-machine)
29 - [Make a copy of the example JJB config file (in the ci-management/ directory)](#make-a-copy-of-the-example-jjb-config-file-in-the-ci-management-directory)
30 - [Retrieve username and API token](#retrieve-username-and-api-token)
31 - [Working with jobs](#working-with-jobs)
32 - [Test a Job](#test-a-job)
33 - [Update a job](#update-a-job)
34 - [Trigger jobs from Jenkins Sandbox](#trigger-jobs-from-jenkins-sandbox)
35 - [Delete a Job](#delete-a-job)
36 - [Modify an Existing Job](#modify-an-existing-job)
37 - [More online documentation](#more-online-documentation)
42 To download **ci-management**, execute the following command to clone the
43 **ci-management** repository.
46 git clone https://gerrit.onap.org/r/ci-management && (cd ci-management && curl -Lo \
47 $(git rev-parse --git-dir)/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg; \
48 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg)
51 Make sure to sync global-jjb submodule using:
53 `git submodule update --init`
55 Once you successfully cloned the repository, next step is to install JJB
56 (Jenkins Job Builder) in order to experiment with Jenkins jobs.
58 ### Install JJB on your machine
62 pip install virtualenv
63 virtualenv onap_sandbox
64 source onap_sandbox/bin/activate
65 pip install jenkins-job-builder
66 jenkins-jobs --version
67 jenkins-jobs test --recursive jjb/
70 ### Make a copy of the example JJB config file (in the ci-management/ directory)
72 Place a copy of the `jenkins.ini.example` file as `jenkins.ini` in your home folder:
75 mkdir -p ~/.config/jenkins_jobs
76 cp jenkins.ini.example ~/.config/jenkins_jobs/jenkins_jobs.ini
79 Modify the resulting `~/.config/jenkins_jobs/jenkins_jobs.ini` with your
80 **Jenkins LFID username** and **API token**
85 keep_descriptions=False
91 user=jwagantall <Provide your Jenkins Sandbox username>
92 password= <Refer below steps to get API token>
93 url=https://jenkins.onap.org/sandbox
94 query_plugins_info=False
96 ### Retrieve username and API token
97 Login to the [Jenkins Sandbox](https://jenkins.onap.org/sandbox/), go to your user
98 page by clicking on your username - `Jenkins User ID` on this page is your Jenkins
99 Sandbox username. Click **Configure** and then click **Add new Token**.
100 After that specify a token name (optional) and click on **Generate** to generate and show
101 new token. Please note down your token and store it securely.
105 To work on existing jobs or create new jobs, navigate to the `ci-management/jjb/` directory where you
106 will find all job templates for the project. Follow the below commands to test,
107 update or delete jobs in your sandbox environment.
111 After you modify or create jobs in the above environment, it's good practice
112 to test the job in the sandbox environment before you submit this job to the production CI environment.
115 jenkins-jobs test jjb/ <job-name>
118 **Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
120 If the job you’d like to test is a template with variables in its name, it must be
121 manually expanded before use. For example, the commonly used template `sdc-{stream}-verify-java`
122 might expand to `sdc-master-verify-java`.
124 A successful test will output the XML description of the Jenkins job described by the
125 specified JJB job name.
127 Execute the following command to pipe-out to a directory:
130 jenkins-jobs test jjb/ <job-name> -o <directoryname>
133 The output directory will contain files with the XML configurations.
137 Ensure you’ve configured your `jenkins_jobs.ini` and verified the changes by
138 outputting valid XML descriptions of the relevant Jenkins jobs. Upon successful
139 verification, execute the following command to update the job to the Jenkins sandbox.
142 jenkins-jobs update jjb/ <job-name>
145 **Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
147 ### Trigger jobs from Jenkins Sandbox
149 Once you push the Jenkins job configuration to the ONAP Sandbox environment,
150 run the job from the Jenkins Sandbox webUI. Follow the below process to trigger the build:
152 Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
154 Step 2: Click on the **job** which you want to trigger, then click
155 **Build with Parameters**, and finally click **Build**.
157 Step 3: Verify the **Build Executor Status** bar and make sure that the build is triggered
158 on the available executor. In Sandbox you may not see all platforms build executors and
159 you don't find many like in production CI environment.
161 Once the job is triggered, click on the build number to view the job
162 details and the console output.
166 Execute the following command to Delete a job from Sandbox:
169 jenkins-jobs delete jjb/ <job-name>
172 **Example:** `jenkins-jobs delete jjb/ sdc-master-verify-java`
174 The above command would delete the `sdc-master-verify-java` job.
176 ### Modify an Existing Job
178 In the ONAP Jenkins sandbox, you can directly edit or modify the job configuration
179 by selecting the job name and clicking on the **Configure** button. Then, click the
180 **Apply** and **Save** buttons to save the job.
182 However, it is recommended to simply modify the job in your terminal and then follow
183 the previously described steps in [Test a Job](#test-a-job) and [Update a Job](#update-a-job) to perform
186 ## More online documentation
188 https://docs.openstack.org/infra/jenkins-job-builder/