summaryrefslogtreecommitdiffstats
path: root/docs/ci
diff options
context:
space:
mode:
authorTrevor Bramwell <tbramwell@linuxfoundation.org>2020-12-14 09:23:24 -0800
committerTrevor Bramwell <tbramwell@linuxfoundation.org>2020-12-14 09:23:24 -0800
commit44e9beb2d26a8454a53dfa9c4b936684526899ac (patch)
treee9690236155ef9da784e9f18cea08edcc574bb7d /docs/ci
parent80212a14b081b32e06181ee55fcfa6820c6d09f4 (diff)
Basic Getting Started guide for OPNFV CI
Adds a basic getting started user guide for OPNFV CI and and overview of the Releng repository structure. Change-Id: I921a66ced75869439903228d9938c321099ef620 Signed-off-by: Trevor Bramwell <tbramwell@linuxfoundation.org>
Diffstat (limited to 'docs/ci')
-rw-r--r--docs/ci/index.rst9
-rw-r--r--docs/ci/user-guide.rst133
2 files changed, 140 insertions, 2 deletions
diff --git a/docs/ci/index.rst b/docs/ci/index.rst
index 08f23ac2f..445552a82 100644
--- a/docs/ci/index.rst
+++ b/docs/ci/index.rst
@@ -8,10 +8,17 @@
OPNFV CI
========
-TBD
+OPNFV continuous integration (CI) is ran on a variety of :doc:`hardware <resources>`
+connected to Jenkins and mangaged through YAML files in the `Releng`_
+repository. These YAML files are read by `Jenkins Job Builder`_ to
+generate and upload Jenkins jobs to the server. See the :doc:`User Guide
+<user-guide>` for resources on getting started with CI for your project.
.. toctree::
:maxdepth: 2
user-guide
resources
+
+.. _Releng: https://gerrit.opnfv.org/gerrit/admin/repos/releng
+.. _Jenkins Job Builder: https://docs.openstack.org/infra/jenkins-job-builder/
diff --git a/docs/ci/user-guide.rst b/docs/ci/user-guide.rst
index 9c9b74a41..b2921f14a 100644
--- a/docs/ci/user-guide.rst
+++ b/docs/ci/user-guide.rst
@@ -8,4 +8,135 @@
CI User Guide
=============
-TBD
+Structure of the Releng Repository
+----------------------------------
+
+jjb/<projects>
+ Individual project CI configurations.
+
+jjb/global
+ Collection of JJB defaults and templates shared by all projects.
+
+global-jjb/
+ Git submodule pointing to `Global-JJB`_, which provides a variety of
+ common `CI jobs`_ such as ReadTheDocs
+ (RTD) builds.
+
+docs/
+ This documentation.
+
+releases/
+ Release configuration files for creating stable branches and tagging
+ repositories and related automation scripts.
+
+utils/
+ Collection of common utilities used by projects
+
+utils/build-server-ansible
+ Ansible configuration for managing build servers. This is where
+ projects can add packages they need for their CI to the servers.
+
+
+CI Setup
+--------
+
+Basic Setup
+~~~~~~~~~~~
+
+All projects are required to have a **+1 Verified** vote in Gerrit in
+order to merge their code. As a new project that comes in may not yet
+know how they want to setup CI, they can pass this validation by
+configuring a 'no-op' job to run against their changesets.
+
+1. Clone the `Releng`_ repository, using the *Clone with commit-msg
+ hook* command under the *SSH* tab (displayed after logging in and
+ uploading an SSH key):
+
+ .. note::
+ <gerrit username> in the command below will be your username in
+ Gerrit when viewing the command on the website.
+
+ For example::
+
+ git clone "ssh://<gerrit username>@gerrit.opnfv.org:29418/releng" && \
+ scp -p -P 29418 <gerrit username>@gerrit.opnfv.org:hooks/commit-msg "releng/.git/hooks/"
+
+
+2. Create a project directory under the *jjb/* directory, and an intial
+ project YAML file::
+
+ mkdir jjb/myproject
+ touch jjb/myproject/myproject-ci-jobs.yaml
+
+3. Modify the project YAML file to add the basic validation job::
+
+ $EDITOR jjb/myproject/myproject-ci-jobs.yaml
+
+ ::
+
+ ---
+ - project:
+ name: myproject
+ project:
+ - '{name}'
+ jobs:
+ - '{project}-verify-basic'
+
+Docker Builds
+~~~~~~~~~~~~~
+
+Docker build are managed through the **jjb/releng/opnfv-docker.yaml**
+file. Modify this file with your project details to enable docker builds
+on merges and tags to your project repository::
+
+ ---
+ - project:
+ name: opnfv-docker'
+
+ [...]
+
+ dockerrepo:
+ [...]
+ - 'myproject':
+ project: 'myproject'
+ <<: *master
+
+
+Documentation Builds
+~~~~~~~~~~~~~~~~~~~~
+
+Documentation is build using they Python Sphinx project. You can read
+more about how these build work and how your documentation should be
+setup in the `opnfvdocs`_ project.
+
+Create a file at **jjb/myproject/myproject-rtd-builds.yaml** with the
+following content::
+
+ ---
+ - project:
+ name: myproject-rtd
+ project: myproject
+ project-name: myproject
+
+ project-pattern: 'myproject'
+ rtd-build-url: <request from LFN IT>
+ rtd-token: <request from LFN IT>
+
+ jobs:
+ - '{project-name}-rtd-jobs'
+
+.. note::
+ Open a ticket with a link to the change adding your documentation
+ at `support.linuxfoundation.org`_ and the LFN IT team will
+ provide you the *rtd-build-url* and *rtd-token*.
+
+This will create jobs to build your project documentation (under *docs/*
+in your project repository) on proposed changes, and trigger a rebuild
+on the RTD site when code is merged in your project.
+
+.. _Jenkins Job Builder: https://docs.openstack.org/infra/jenkins-job-builder/
+.. _Releng: https://gerrit.opnfv.org/gerrit/admin/repos/releng
+.. _Global-JJB: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html
+.. _CI jobs: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html#global-jjb-templates
+.. _opnfvdocs: https://docs.opnfv.org/en/latest/how-to-use-docs/index.html
+.. _support.linuxfoundation.org: https://jira.linuxfoundation.org/plugins/servlet/theme/portal/2/create/145