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)
41 To download **ci-management**, execute the following command to clone the
42 **ci-management** repository.
45 git clone https://gerrit.onap.org/r/ci-management && (cd ci-management && curl -Lo \
46 $(git rev-parse --git-dir)/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg; \
47 chmod +x $(git rev-parse --git-dir)/hooks/commit-msg)
50 Make sure to sync global-jjb submodule using:
52 `git submodule update --init`
54 Once you successfully cloned the repository, next step is to install JJB
55 (Jenkins Job Builder) in order to experiment with Jenkins jobs.
57 ### Install JJB on your machine
61 pip install virtualenv
62 virtualenv onap_sandbox
63 source onap_sandbox/bin/activate
64 pip install jenkins-job-builder
65 jenkins-jobs --version
66 jenkins-jobs test --recursive jjb/
69 ### Make a copy of the example JJB config file (in the ci-management/ directory)
71 Place a copy of the `jenkins.ini.example` file as `jenkins.ini` in your home folder:
74 mkdir -p ~/.config/jenkins_jobs
75 cp jenkins.ini.example ~/.config/jenkins_jobs/jenkins_jobs.ini
78 Modify the resulting `~/.config/jenkins_jobs/jenkins_jobs.ini` with your
79 **Jenkins LFID username** and **API token**. Make sure that your account has the necessary permissions (request them via the [LFN help desk](https://jira.linuxfoundation.org/plugins/servlet/desk/portal/2/create/35) if not)!
84 keep_descriptions=False
90 user=jwagantall <Provide your Jenkins Sandbox username>
91 password= <Refer below steps to get API token>
92 url=https://jenkins.onap.org/sandbox
93 query_plugins_info=False
96 ### Retrieve username and API token
98 Login to the [Jenkins Sandbox](https://jenkins.onap.org/sandbox/), go to your user
99 page by clicking on your username - `Jenkins User ID` on this page is your Jenkins
100 Sandbox username. Click **Configure** and then click **Add new Token**.
101 After that specify a token name (optional) and click on **Generate** to generate and show
102 new token. Please note down your token and store it securely.
106 To work on existing jobs or create new jobs, navigate to the `ci-management/jjb/` directory where you
107 will find all job templates for the project. Follow the below commands to test,
108 update or delete jobs in your sandbox environment.
112 After you modify or create jobs in the above environment, it's good practice
113 to test the job in the sandbox environment before you submit this job to the production CI environment.
116 jenkins-jobs test jjb/ <job-name>
119 **Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
121 If the job you’d like to test is a template with variables in its name, it must be
122 manually expanded before use. For example, the commonly used template `sdc-{stream}-verify-java`
123 might expand to `sdc-master-verify-java`.
125 A successful test will output the XML description of the Jenkins job described by the
126 specified JJB job name.
128 Execute the following command to pipe-out to a directory:
131 jenkins-jobs test jjb/ <job-name> -o <directoryname>
134 The output directory will contain files with the XML configurations.
138 Ensure you’ve configured your `jenkins_jobs.ini` and verified the changes by
139 outputting valid XML descriptions of the relevant Jenkins jobs. Upon successful
140 verification, execute the following command to update the job to the Jenkins sandbox.
143 jenkins-jobs update jjb/ <job-name>
146 **Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
148 ### Trigger jobs from Jenkins Sandbox
150 Once you push the Jenkins job configuration to the ONAP Sandbox environment,
151 run the job from the Jenkins Sandbox webUI. Follow the below process to trigger the build:
153 Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
155 Step 2: Click on the **job** which you want to trigger, then click
156 **Build with Parameters**, and finally click **Build**.
158 Step 3: Verify the **Build Executor Status** bar and make sure that the build is triggered
159 on the available executor. In Sandbox you may not see all platforms build executors and
160 you don't find many like in production CI environment.
162 Once the job is triggered, click on the build number to view the job
163 details and the console output.
167 Execute the following command to Delete a job from Sandbox:
170 jenkins-jobs delete jjb/ <job-name>
173 **Example:** `jenkins-jobs delete jjb/ sdc-master-verify-java`
175 The above command would delete the `sdc-master-verify-java` job.
177 ### Modify an Existing Job
179 In the ONAP Jenkins sandbox, you can directly edit or modify the job configuration
180 by selecting the job name and clicking on the **Configure** button. Then, click the
181 **Apply** and **Save** buttons to save the job.
183 However, it is recommended to simply modify the job in your terminal and then follow
184 the previously described steps in [Test a Job](#test-a-job) and [Update a Job](#update-a-job) to perform
187 ## More online documentation
189 https://docs.openstack.org/infra/jenkins-job-builder/