.. _quick-start-guide:

Quick Start Guide
=================

This guide was made with the impatient in mind so explanation is sparse.
It will guide users through a set of typical use cases for JJB using the same
job definitions we use to test JJB.

#. Clone the repository_ to get the JJB job definition examples_
#. The :doc:`installation` can be either from pypi_ (released version) or from the clone (master).

Usage of the commands below assumes that you are at the root of the cloned directory.

.. _repository: https://opendev.org/jjb/jenkins-job-builder/
.. _pypi: https://pypi.org/project/jenkins-job-builder/
.. _examples: https://opendev.org/jjb/jenkins-job-builder/src/branch/master/tests


.. _use-case-1:

Use Case 1: Test a job definition
---------------------------------

JJB creates Jenkins XML configuration file from a YAML/JSON definition file and
just uploads it to Jenkins.  JJB provides a convenient ``test`` command to allow
you to validate the XML before you attempt to upload it to Jenkins.

Test a YAML job definition::

    jenkins-jobs test tests/yamlparser/job_fixtures/templates002.yaml


The above command prints the generated Jenkins XML to the console.  If you
prefer to send it to a directory::

    jenkins-jobs test -o output tests/yamlparser/job_fixtures/templates002.yaml


The `output` directory will contain files with the XML configurations.

.. _use-case-2:

Use Case 2: Updating Jenkins Jobs
---------------------------------

Once you've tested your job definition and are happy with it then you can use the
``update`` command to deploy the job to Jenkins.  The ``update`` command requires a
configuration file.  An example file is supplied in the etc folder, you should
update it to match your Jenkins master::

    jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/yamlparser/job_fixtures/templates002.yaml

The above command will update your Jenkins master with the generated jobs.

**Caution**: JJB caches Jenkins job information locally.  Changes
made using the Jenkins UI will not update that cache, which may
lead to confusion.  See :ref:`updating-jobs` for more information.

.. _use-case-3:

Use Case 3: Working with JSON job definitions
---------------------------------------------

You can also define your jobs in json instead of yaml::

    jenkins-jobs --conf etc/jenkins_jobs.ini-sample update tests/jsonparser/fixtures/simple.json

The above command just uses a simple job definition.  You can also convert any
of the YAML examples to JSON and feed that to JJB.

.. _use-case-4:

Use Case 4: Deleting a job
--------------------------

To delete a job::

    jenkins-jobs --conf etc/jenkins_jobs.ini-sample delete simple

The above command deletes the job `simple` from the Jenkins master.

.. _use-case-5:

Use Case 5: Providing plugins info
----------------------------------

To generate a plugins info, using an account with Administrator rights::

    jenkins-jobs get-plugins-info -o plugins_info.yaml

To run JJB update using the plugins_info.yaml::

    jenkins-jobs update -p plugins_info.yaml ./myjobs

Please refer to the jenkins-jobs :ref:`command-reference` and the
:doc:`definition` pages for more details.
