[CPS] Jobs for newdelhi branch

[ci-management.git] / Sandbox_Setup.md

diff --git a/Sandbox_Setup.md b/Sandbox_Setup.md
index bd734c7..f7101c6 100644 (file)
--- a/Sandbox_Setup.md
+++ b/Sandbox_Setup.md
@@ -1,4 +1,4 @@
-## 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
 
 ONAP Jenkins Sandbox provides you Jenkins Job testing/experimentation environment
 that can be used before pushing job templates to the production


@@ -23,23 +23,40 @@ required to access Gerrit & Jenkins. Also, to extend your permissions for upload
 Jenkins configurations to Sandbox environment, you must raise a ticket to
 [Linux Foundation Help Center](https://support.linuxfoundation.org)
 
 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-management** repository.
 
 To download **ci-management**, execute the following command to clone the
 **ci-management** repository.
 

-`git clone https://gerrit.onap.org/r/ci-management && (cd ci-management && curl -Lo \
+```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; \
 $(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)`
+chmod +x $(git rev-parse --git-dir)/hooks/commit-msg)
+```

 
 Make sure to sync global-jjb submodule using:
 
 `git submodule update --init`
 
 
 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.
 
 (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
 pip install virtualenv
 virtualenv onap_sandbox
 cd ci-management
 pip install virtualenv
 virtualenv onap_sandbox


@@ -51,14 +68,17 @@ jenkins-jobs test --recursive jjb/
 
 ### 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)
 

-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 ~/.config/jenkins_jobs/jenkins_jobs.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** and **API token**
+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
 [job_builder]
 ignore_cache=True
 keep_descriptions=False


@@ -72,22 +92,29 @@ password= <Refer below steps to get API token>
 url=https://jenkins.onap.org/sandbox
 query_plugins_info=False
 ```
 url=https://jenkins.onap.org/sandbox
 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
 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 **Add new 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.
 
 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 `ci-management/jjb/` directory where you
 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,
+will find all job templates for the project. Follow the below commands to test,

 update or delete jobs in your sandbox environment.
 
 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
 
 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 test jjb/ <job-name>`
+```sh
+jenkins-jobs test jjb/ <job-name>
+```

 
 **Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
 
 
 **Example:** `jenkins-jobs test jjb/ sdc-master-verify-java`
 


@@ -100,28 +127,28 @@ specified JJB job name.
 
 Execute the following command to pipe-out to a directory:
 
 
 Execute the following command to pipe-out to a directory:
 

-`jenkins-jobs 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.
 
 
 The output directory will contain files with the XML configurations.
 

-## To Update a job:
+### Update a job

 
 

-Ensure you’ve configured your `jenkins_jobs.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 update jjb/ <job-name>`
+```sh
+jenkins-jobs update jjb/ <job-name>
+```

 
 **Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
 
 
 **Example:** `jenkins-jobs update jjb/ sdc-master-verify-java`
 

-Note that there will be some 403 errors along the way for failed view creation attempts even
-when the job creation succeeds.
-
-## Trigger jobs from Jenkins Sandbox:
+### Trigger jobs from Jenkins Sandbox

 
 Once you push the Jenkins job configuration to the ONAP Sandbox environment,
 
 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/)
 
 
 Step 1: Login into the [Jenkins Sandbox WebUI](https://jenkins.onap.org/sandbox/)
 


@@ -135,26 +162,28 @@ you don't find many like in production CI environment.
 Once the job is triggered, click on the build number to view the job
 details and the console output.
 
 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:
 
 
 Execute the following command to Delete a job from Sandbox:
 

-`jenkins-jobs delete jjb/ <job-name>`
+```sh
+jenkins-jobs delete jjb/ <job-name>
+```

 
 **Example:** `jenkins-jobs delete jjb/ sdc-master-verify-java`
 
 The above command would delete the `sdc-master-verify-java` job.
 
 
 **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
 
 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.
 
 your modifications.
 

-## More online documentation:
+## More online documentation

 
 https://docs.openstack.org/infra/jenkins-job-builder/
 
 https://docs.openstack.org/infra/jenkins-job-builder/