-## ONAP Jenkins Sandbox Process:
+# ONAP Jenkins Sandbox Process
ONAP Jenkins Sandbox provides you Jenkins Job testing/experimentation environment
that can be used before pushing job templates to the production
It is configured similar to the ONAP [ci-management] production instance;
however, it cannot publish artifacts or vote in Gerrit. Be aware that this is a
-test environment, and as such there a limited allotment of minions to test on
+test environment, and as such there is a limited allotment of minions to test on
before pushing code to the ONAP repos.
Keep the following points in mind prior to beginning work on ONAP Jenkins Sandbox
environment:
these VMs directly.
Before you proceed further, ensure you have a Linux Foundation ID (LFID), which is
-required to access Gerrit & Jenkins. Also, to get an access to Sandbox environment
-please send email to helpdesk@onap.org (LF helpdesk team)
+required to access Gerrit & Jenkins. Also, to extend your permissions for uploading
+Jenkins configurations to Sandbox environment, you must raise a ticket to
+[Linux Foundation Help Center](https://support.linuxfoundation.org)
+
+- [ONAP Jenkins Sandbox Process](#onap-jenkins-sandbox-process)
+ - [Setup](#setup)
+ - [Install JJB on your machine](#install-jjb-on-your-machine)
+ - [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)
+ - [Retrieve username and API token](#retrieve-username-and-api-token)
+ - [Working with jobs](#working-with-jobs)
+ - [Test a Job](#test-a-job)
+ - [Update a job](#update-a-job)
+ - [Trigger jobs from Jenkins Sandbox](#trigger-jobs-from-jenkins-sandbox)
+ - [Delete a Job](#delete-a-job)
+ - [Modify an Existing Job](#modify-an-existing-job)
+ - [More online documentation](#more-online-documentation)
+
+## Setup
To download **ci-management**, execute the following command to clone the
-**ci-managment** repository.
+**ci-management** repository.
-`git clone ssh://<LFID>@gerrit.onap.org:29418/ci-management --recursive && scp -p -P 29418 \
-<LFID>@gerrit.onap.org:hooks/commit-msg ci-management/.git/hooks/`
+```sh
+git clone https://gerrit.onap.org/r/ci-management && (cd ci-management && curl -Lo \
+$(git rev-parse --git-dir)/hooks/commit-msg https://gerrit.onap.org/r/tools/hooks/commit-msg; \
+chmod +x $(git rev-parse --git-dir)/hooks/commit-msg)
+```
Make sure to sync global-jjb submodule using:
`git submodule update --init`
-Once you successfully clone the repository, next step is to install JJB
+Once you successfully cloned the repository, next step is to install JJB
(Jenkins Job Builder) in order to experiment with Jenkins jobs.
-### Execute the following commands to install JJB on your machine:
+### Install JJB on your machine
-```
+```sh
cd ci-management
-sudo apt-get install python-virtualenv
+pip install virtualenv
virtualenv onap_sandbox
source onap_sandbox/bin/activate
pip install jenkins-job-builder
jenkins-jobs test --recursive jjb/
```
-### Make a copy of the example JJB config file (in the builder/ directory)
+### Make a copy of the example JJB config file (in the ci-management/ directory)
-Backup the jenkins.ini.example to jenkins.ini
+Place a copy of the `jenkins.ini.example` file as `jenkins.ini` in your home folder:
-`cp jenkins.ini.example jenkins.ini`
+```sh
+mkdir -p ~/.config/jenkins_jobs
+cp jenkins.ini.example ~/.config/jenkins_jobs/jenkins_jobs.ini
+```
-After copying the jenkins.ini.example, modify `jenkins.ini` with your
-**Jenkins LFID username**, **API token** and **ONAP jenkins sandbox URL**
+Modify the resulting `~/.config/jenkins_jobs/jenkins_jobs.ini` with your
+**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)!
-```
+```ini
[job_builder]
ignore_cache=True
keep_descriptions=False
-include_path=.:scripts:~/git/
+include_path=.
recursive=True
+retain_anchors=True
[jenkins]
user=jwagantall <Provide your Jenkins Sandbox username>
password= <Refer below steps to get API token>
url=https://jenkins.onap.org/sandbox
-This is deprecated, use job_builder section instead
-ignore_cache=True
+query_plugins_info=False
```
-### How to retrieve API token?
+
+### Retrieve username and API token
+
Login to the [Jenkins Sandbox](https://jenkins.onap.org/sandbox/), go to your user
-page by clicking on your username. Click **Configure** and then click **Show API Token**.
+page by clicking on your username - `Jenkins User ID` on this page is your Jenkins
+Sandbox username. Click **Configure** and then click **Add new Token**.
+After that specify a token name (optional) and click on **Generate** to generate and show
+new token. Please note down your token and store it securely.
+
+## Working with jobs
-To work on existing jobs or create new jobs, navigate to the `/jjb` directory where you
-will find all job templates for the project. Follow the below commands to test,
+To work on existing jobs or create new jobs, navigate to the `ci-management/jjb/` directory where you
+will find all job templates for the project. Follow the below commands to test,
update or delete jobs in your sandbox environment.
-## To Test a Job:
+### Test a Job
After you modify or create jobs in the above environment, it's good practice
-to test the job in sandbox environment before you submit this job to production CI environment.
+to test the job in the sandbox environment before you submit this job to the production CI environment.
-`jenkins-jobs --conf jenkins.ini test jjb/ <job-name>`
+```sh
+jenkins-jobs test jjb/ <job-name>
+```
-**Example:** `jenkins-jobs --conf jenkins.ini test jjb/ sdc-master-verify-java`
+**Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
If the job you’d like to test is a template with variables in its name, it must be
manually expanded before use. For example, the commonly used template `sdc-{stream}-verify-java`
Execute the following command to pipe-out to a directory:
-`jenkins-jobs --conf jenkins.ini test jjb/ <job-name> -o <directoryname>`
+```sh
+jenkins-jobs test jjb/ <job-name> -o <directoryname>
+```
The output directory will contain files with the XML configurations.
-## To Update a job:
+### Update a job
-Ensure you’ve configured your `jenkins.ini` and verified it by
-outputting valid XML descriptions of Jenkins jobs. Upon successful
-verification, execute the following command to update the job to the
-Jenkins sandbox.
+Ensure you’ve configured your `jenkins_jobs.ini` and verified the changes by
+outputting valid XML descriptions of the relevant Jenkins jobs. Upon successful
+verification, execute the following command to update the job to the Jenkins sandbox.
-`jenkins-jobs --conf jenkins.ini update jjb/ <job-name>`
+```sh
+jenkins-jobs update jjb/ <job-name>
+```
-**Example:** `jenkins-jobs --conf jenkins.ini update jjb/ sdc-master-verify-java`
+**Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
-## Trigger jobs from Jenkins Sandbox:
+### Trigger jobs from Jenkins Sandbox
Once you push the Jenkins job configuration to the ONAP Sandbox environment,
-run the job from Jenkins Sandbox webUI. Follow the below process to trigger the build:
+run the job from the Jenkins Sandbox webUI. Follow the below process to trigger the build:
Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
Once the job is triggered, click on the build number to view the job
details and the console output.
-## To Delete a Job:
+### Delete a Job
Execute the following command to Delete a job from Sandbox:
-`jenkins-jobs --conf jenkins.ini delete jjb/ <job-name>`
+```sh
+jenkins-jobs delete jjb/ <job-name>
+```
-**Example:** `jenkins-jobs --conf jenkins.ini delete jjb/ sdc-master-verify-java`
+**Example:** `jenkins-jobs delete jjb/ sdc-master-verify-java`
The above command would delete the `sdc-master-verify-java` job.
-## Modify an Existing Job:
+### Modify an Existing Job
In the ONAP Jenkins sandbox, you can directly edit or modify the job configuration
by selecting the job name and clicking on the **Configure** button. Then, click the
**Apply** and **Save** buttons to save the job.
However, it is recommended to simply modify the job in your terminal and then follow
-the previously described steps in **To Test a Job** and **To Update a Job** to perform
+the previously described steps in [Test a Job](#test-a-job) and [Update a Job](#update-a-job) to perform
your modifications.
-## More online documentation:
+## More online documentation
https://docs.openstack.org/infra/jenkins-job-builder/