Jenkins Sandbox
---------------
-The `jenkins-sandbox`_ instance's purpose is to allow projects to test their JJB
-setups before merging their code over to the RelEng master silo. It is
-configured similarly to the master instance, although it cannot publish
-artifacts or vote in Gerrit.
-
-If your project requires access to the sandbox please open an OpenDaylight
-Helpdesk ticket (<helpdesk@opendaylight.org>) and provide your ODL ID.
-
-Notes Regarding the Sandbox
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-* Jobs are automatically deleted every Saturday at 08:00 UTC
-* Committers can login and configure Jenkins jobs in the sandbox directly
- (unlike with the master silo)
-* Sandbox configuration mirrors the master silo when possible
-* Sandbox jobs can NOT upload artifacts to Nexus
-* Sandbox jobs can NOT vote on Gerrit
-
-Configuration
-^^^^^^^^^^^^^
-
-Make sure you have Jenkins Job Builder [properly installed](#jjb_install).
-
-If you do not already have access, open an OpenDaylight Helpdesk ticket
-(<helpdesk@opendaylight.org>) to request access to ODL's sandbox instance.
-Integration/Test (`integration-test-wiki`_) committers have access by default.
-
-JJB reads user-specific configuration from a `jenkins.ini`_. An
-example is provided by releng/builder at `example-jenkins.ini`_.
-
-.. code-block:: bash
-
- # If you don't have RelEng/Builder's repo, clone it
- $ git clone --recursive https://git.opendaylight.org/gerrit/p/releng/builder.git
- # Make a copy of the example JJB config file (in the builder/ directory)
- $ cp jenkins.ini.example jenkins.ini
- # Edit jenkins.ini with your username, API token and ODL's sandbox URL
- $ cat jenkins.ini
- <snip>
- [job_builder]
- retain_anchors=True
-
- [jenkins]
- user=<your ODL username>
- password=<your ODL Jenkins sandbox API token>
- url=https://jenkins.opendaylight.org/sandbox
- <snip>
-
-To get your API token, `login to the Jenkins **sandbox** instance
-<jenkins-sandbox-login_>`_ (*not
-the main master Jenkins instance, different tokens*), go to your user page (by
-clicking on your username, for example), click "Configure" and then "Show API
-Token".
-
-Manual Method
-^^^^^^^^^^^^^
-
-If you `installed JJB locally into a virtual environment
-<Installing Jenkins Job Builder_>`_,
-you should now activate that virtual environment to access the `jenkins-jobs`
-executable.
-
-.. code-block:: bash
-
- $ workon jjb
- (jjb)$
-
-You'll want to work from the root of the RelEng/Builder repo, and you should
-have your `jenkins.ini` file [properly configured](#sandbox_config).
-
-Testing Jobs
-^^^^^^^^^^^^
-
-It's good practice to use the `test` command to validate your JJB files before
-pushing them.
-
-.. code-block:: bash
-
- jenkins-jobs --conf jenkins.ini test jjb/ <job-name>
-
-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
-`{project}-csit-verify-1node-{functionality}` might expand to
-`ovsdb-csit-verify-1node-netvirt`.
-
-.. code-block:: bash
-
- jenkins-jobs --conf jenkins.ini test jjb/ ovsdb-csit-verify-1node-netvirt
-
-Successful tests output the XML description of the Jenkins job described by
-the specified JJB job name.
-
-Pushing Jobs
-^^^^^^^^^^^^
-
-Once you've `configured your \`jenkins.ini\` <Configuration_>`_ and `verified your
-JJB jobs <Testing Jobs_>`_ produce valid XML descriptions of Jenkins jobs you
-can push them to the Jenkins sandbox.
-
-Add the --jobs-only (-j) option to push only jobs to Jenkins sandbox. Pushing
-views to Jenkins sandbox requires admin access.
-
-.. important::
-
- When pushing with `jenkins-jobs`, a log message with the number
- of jobs you're pushing will be issued, typically to stdout.
- **If the number is greater than 1** (or the number of jobs you
- passed to the command to push) then you are pushing too many
- jobs and should **`ctrl+c` to cancel the upload**. Else you will
- flood the system with jobs.
-
- .. code-block:: bash
-
- INFO:jenkins_jobs.builder:Number of jobs generated: 1
-
- **Failing to provide the final `<job-name>` param will push all
- jobs!**
-
- .. code-block:: bash
-
- # Don't push all jobs by omitting the final param! (ctrl+c to abort)
- jenkins-jobs --conf jenkins.ini update -j jjb/ <job-name>
-
-Alternatively, you can push a job to the Jenkins sandbox with a special comment in a
-releng/builder gerrit patch. The job will be based off of the code your patch is
-based upon. Meaning, if your patch is changing something related to the job you are
-pushing, those changes will exist in the sandbox job. The format of the comment is::
-
- jjb-deploy <job name>
-
-.. note::
-
- Also note that wildcards can be used in <job name> which
- will expand all jobs that exist for the pattern.
-
-Running Jobs
-^^^^^^^^^^^^
-
-Once you have your Jenkins job configuration `pushed to the
-Sandbox <Pushing Jobs_>`_ you can trigger it to run.
-
-Find your newly-pushed job on the `Sandbox's web UI <jenkins-sandbox_>`_. Click
-on its name to see the job's details.
-
-Make sure you're `logged in <jenkins-sandbox-login_>`_ to the Sandbox.
-
-Click "Build with Parameters" and then "Build".
-
-Wait for your job to be scheduled and run. Click on the job number to see
-details, including console output.
-
-Make changes to your JJB configuration, re-test, re-push and re-run until
-your job is ready.
+URL: https://jenkins.opendaylight.org/sandbox
+Jenkins Sandbox documentation can be found in the
+:doc:`LF Jenkins Sandbox Guide <lfdocs:jenkins-sandbox>`.
.. _example-jenkins.ini: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=jenkins.ini.example
.. _integration-test-wiki: https://wiki.opendaylight.org/view/Integration/Test
.. _jenkins-master: https://jenkins.opendaylight.org/releng
-.. _jenkins-sandbox: https://jenkins.opendaylight.org/sandbox
-.. _jenkins-sandbox-login: https://jenkins.opendaylight.org/sandbox/login
.. _jenkins.ini: http://docs.openstack.org/infra/jenkins-job-builder/execution.html#configuration-file
.. _jjb-autoupdate-project.py: https://git.opendaylight.org/gerrit/gitweb?p=releng/builder.git;a=blob;f=scripts/jjb-autoupdate-project.py
.. _jjb-docs: http://ci.openstack.org/jenkins-job-builder/
Code Review / releng / builder.git / commitdiff