docs/ci/user-guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3 .. (c) Open Platform for NFV Project, Inc. and its contributors
   4
   5 .. _ci-user-guide:
   6
   7 =============
   8 CI User Guide
   9 =============
  10
  11 Structure of the Releng Repository
  12 ----------------------------------
  13
  14 jjb/<projects>
  15    Individual project CI configurations.
  16
  17 jjb/global
  18    Collection of JJB defaults and templates shared by all projects.
  19
  20 global-jjb/
  21    Git submodule pointing to `Global-JJB`_, which provides a variety of
  22    common `CI jobs`_ such as ReadTheDocs
  23    (RTD) builds.
  24
  25 docs/
  26   This documentation.
  27
  28 releases/
  29   Release configuration files for creating stable branches and tagging
  30   repositories and related automation scripts.
  31
  32 utils/
  33   Collection of common utilities used by projects
  34
  35 utils/build-server-ansible
  36   Ansible configuration for managing build servers. This is where
  37   projects can add packages they need for their CI to the servers.
  38
  39
  40 CI Setup
  41 --------
  42
  43 Basic Setup
  44 ~~~~~~~~~~~
  45
  46 All projects are required to have a **+1 Verified** vote in Gerrit in
  47 order to merge their code. As a new project that comes in may not yet
  48 know how they want to setup CI, they can pass this validation by
  49 configuring a 'no-op' job to run against their changesets.
  50
  51 1. Clone the `Releng`_ repository, using the *Clone with commit-msg
  52    hook* command under the *SSH* tab (displayed after logging in and
  53    uploading an SSH key):
  54
  55    .. note::
  56      <gerrit username> in the command below will be your username in
  57      Gerrit when viewing the command on the website.
  58
  59    For example::
  60
  61      git clone "ssh://<gerrit username>@gerrit.opnfv.org:29418/releng" && \
  62      scp -p -P 29418 <gerrit username>@gerrit.opnfv.org:hooks/commit-msg "releng/.git/hooks/"
  63
  64
  65 2. Create a project directory under the *jjb/* directory, and an intial
  66    project YAML file::
  67
  68      mkdir jjb/myproject
  69      touch jjb/myproject/myproject-ci-jobs.yaml
  70
  71 3. Modify the project YAML file to add the basic validation job::
  72
  73      $EDITOR jjb/myproject/myproject-ci-jobs.yaml
  74
  75    ::
  76
  77      ---
  78      - project:
  79          name: myproject
  80          project:
  81            - '{name}'
  82          jobs:
  83            - '{project}-verify-basic'
  84
  85 Docker Builds
  86 ~~~~~~~~~~~~~
  87
  88 Docker build are managed through the **jjb/releng/opnfv-docker.yaml**
  89 file. Modify this file with your project details to enable docker builds
  90 on merges and tags to your project repository::
  91
  92   ---
  93   - project:
  94       name: opnfv-docker'
  95
  96       [...]
  97
  98       dockerrepo:
  99         [...]
 100         - 'myproject':
 101           project: 'myproject'
 102           <<: *master
 103
 104
 105 Documentation Builds
 106 ~~~~~~~~~~~~~~~~~~~~
 107
 108 Documentation is build using they Python Sphinx project. You can read
 109 more about how these build work and how your documentation should be
 110 setup in the `opnfvdocs`_ project.
 111
 112 Create a file at **jjb/myproject/myproject-rtd-builds.yaml** with the
 113 following content::
 114
 115   ---
 116   - project:
 117       name: myproject-rtd
 118       project: myproject
 119       project-name: myproject
 120
 121       project-pattern: 'myproject'
 122       rtd-build-url: <request from LFN IT>
 123       rtd-token: <request from LFN IT>
 124
 125       jobs:
 126         - '{project-name}-rtd-jobs'
 127
 128 .. note::
 129    Open a ticket with a link to the change adding your documentation
 130    at `support.linuxfoundation.org`_ and the LFN IT team will
 131    provide you the *rtd-build-url* and *rtd-token*.
 132
 133 This will create jobs to build your project documentation (under *docs/*
 134 in your project repository) on proposed changes, and trigger a rebuild
 135 on the RTD site when code is merged in your project.
 136
 137 .. _Jenkins Job Builder: https://docs.openstack.org/infra/jenkins-job-builder/
 138 .. _Releng: https://gerrit.opnfv.org/gerrit/admin/repos/releng
 139 .. _Global-JJB: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html
 140 .. _CI jobs: https://docs.releng.linuxfoundation.org/projects/global-jjb/en/latest/index.html#global-jjb-templates
 141 .. _opnfvdocs: https://docs.opnfv.org/en/latest/how-to-use-docs/index.html
 142 .. _support.linuxfoundation.org: https://jira.linuxfoundation.org/plugins/servlet/theme/portal/2/create/145