Minor rewording and reformatting of release doc

[releng/global-jjb.git] / docs / jjb / lf-release-jobs.rst

diff --git a/docs/jjb/lf-release-jobs.rst b/docs/jjb/lf-release-jobs.rst
index 8565235..0a9cc09 100644 (file)
--- a/docs/jjb/lf-release-jobs.rst
+++ b/docs/jjb/lf-release-jobs.rst
@@ -1,34 +1,183 @@
 .. _lf-global-jjb-release:
 
 .. _lf-global-jjb-release:
 

-####################
-Releng Release Files
-####################
+#######################
+Self-Serve Release Jobs
+#######################

 
 

-Projects can create a releases directory and then place a release file in it.
-Jenkins will pick this up and then promote the artifact from the staging log
-directory (log_dir) and tag the release with the defined version.
-if a maven_central_url is given artifact will be pushed there as well.
+Self-serve release jobs allow a project team to direct Jenkins to promote jar files or container
+images from staging areas to release areas.  To trigger the action, create a releases/ or .releases/
+directory, place one or more release yaml files in it, and submit the change to Gerrit.  Upon merge
+of the change, Jenkins will sign the reference(s) extrapolated by log_dir and promote the artifact(s).

 
 

-example of a projects release file
+Release jobs can also be triggered from Jenkins via the "Build with parameters" action, removing the
+need for a release yaml file. The parameters must be filled out in the same way as a release file,
+except for the special USE_RELEASE_FILE and DRY_RUN check boxes. The USE_RELEASE_FILE check box must
+be unchecked if the job is expected to run with a release file, while passing the required information
+as build parameters. Similarly, the DRY_RUN check box must be unchecked if the job needs to be tested
+while skipping repository promotion to Nexus.
+
+The special parameters are as follows::
+
+    GERRIT_BRANCH = master
+    VERSION = 1.0.0
+    LOG_DIR = example-project-maven-stage-master/17/
+    DISTRIBUTION_TYPE = maven
+    USE_RELEASE_FILE = false
+    DRY_RUN = false
+
+.. note::
+
+   The release files regex is: (releases\/.*\.yaml|\.releases\/.*\.yaml).
+   In words, the directory name can be ".releases" or "releases"; the file
+   name can be any name with suffix ".yaml".
+
+Example of a maven release file:

 
 .. code-block:: bash
 
 
 .. code-block:: bash
 

-    $ cat releases/1.0.0.yaml
+    $ cat releases/maven-1.0.0.yaml

     ---
     distribution_type: 'maven'
     version: '1.0.0'
     ---
     distribution_type: 'maven'
     version: '1.0.0'

-    project: 'zzz-test-release'
-    log_dir: 'zzz-test-release-maven-stage-master/17/'
-    maven_central_url: 'oss.sonatype.org'
+    project: 'example-project'
+    log_dir: 'example-project-maven-stage-master/17/'
+
+
+Example of a container release file:
+
+.. code-block:: bash
+
+    $ cat releases/container-1.0.0.yaml
+    ---
+    distribution_type: 'container'
+    version: '1.0.0'
+    project: 'test'
+    containers:
+        - name: test-backend
+          version: 1.0.0-20190806T184921Z
+        - name: test-frontend
+          version: 1.0.0-20190806T184921Z
+
+
+.. note::
+
+   Job should be appended under gerrit-maven-stage
+
+Example of a terse Jenkins job to call the global-jjb macro:
+
+.. code-block:: none
+
+    - gerrit-maven-stage:
+        sign-artifacts: true
+        build-node: centos7-docker-8c-8g
+        maven-versions-plugin: true
+    - '{project-name}-gerrit-release-jobs':
+        build-node: centos7-docker-8c-8g
+
+.. note::
+
+   Release Engineers: please follow the setup guide below before adding the job definition.
+
+
+Setup for LFID, Nexus, Jenkins and Gerrit
+=========================================
+
+LFID
+====
+
+Create an ``lfid`` and an ``ssh-key``
+
+``YOUR_RELEASE_USERNAME`` for example: onap-release
+
+``YOUR_RELEASE_EMAIL`` for example: collab-it+onap-release@linuxfoundation.org
+
+ssh-key example:
+
+.. code-block:: bash
+
+   ssh-keygen -t rsa -C "collab-it+odl-release@linuxfoundation.org"  -f /tmp/odl-release
+
+
+`Create an LFID with the above values <https://identity.linuxfoundation.org>`_
+
+
+Nexus
+=====
+
+Create a Nexus account called ``'jenkins-release'`` with promote privileges.
+
+.. image:: ../_static/nexus-promote-privs.png

 
 

-lftools nexus release is used so there must be a lftoolsini section in jenkins
-configfiles with a [nexus] section for auth.
+Gerrit
+======
+
+Log into your Gerrit with ``YOU_RELEASE_USERNAME``, upload the public part of the ``ssh-key`` you
+created earlier. Log out of Gerrit and log in again with your normal account for the next steps.
+
+
+In Gerrit create a new group called ``self-serve-release`` and give it direct push rights via ``All-Projects``
+Add ``YOUR_RELEASE_USERNAME`` to group ``self-serve-release`` and group ``Non-Interactive Users``
+
+
+In All project, grant group self-serve-release the following:
+
+.. code-block:: none
+
+    [access "refs/heads/*"]
+      push = group self-serve-release
+    [access "refs/tags/*"]
+      createTag = group self-serve-release
+      createSignedTag = group self-serve-release
+      forgeCommitter = group self-serve-release
+      push = group self-serve-release
+
+
+Jenkins
+=======
+
+Add a global credential to Jenkins called ``jenkins-release`` and set the ID: ``'jenkins-release'``
+as its value insert the private half of the ``ssh-key`` that you created for your Gerrit user.
+
+Add Global vars in Jenkins:
+Jenkins configure -> Global properties -> Environment variables
+
+``RELEASE_USERNAME = YOUR_RELEASE_USERNAME``
+``RELEASE_EMAIL = YOUR_RELEASE_EMAIL``
+
+Jenkins configure -> Managed Files -> Add a New Config -> Custom File
+
+id: signing-pubkey
+Name: SIGNING_PUBKEY (optional)
+Comment: SIGNING_PUBKEY (optional)
+
+Content: (Ask Andy for the public signing key)
+-----BEGIN PGP PUBLIC KEY BLOCK-----
+
+
+Add or edit the managed file in Jenkins called ``lftoolsini``, appending a nexus section:
+Jenkins Settings -> Managed files -> Add (or edit) -> Custom file
+
+.. code-block:: none
+
+   [nexus.example.com]
+   username=jenkins-release
+   password=<plaintext password>
+
+Ci-management
+=============
+
+Upgrade your project's global-jjb if needed, then add the following to your global defaults
+file (e.g., jjb/defaults.yaml).
+
+.. code-block:: bash
+
+   jenkins-ssh-release-credential: 'jenkins-release'

 
 Macros
 ======
 
 
 Macros
 ======
 

-lf-releases
------------
+lf-release
+----------

 
 Release verify and merge jobs are the same except for their scm, trigger, and
 builders definition. This anchor is the common template.
 
 Release verify and merge jobs are the same except for their scm, trigger, and
 builders definition. This anchor is the common template.


@@ -39,34 +188,20 @@ Job Templates
 Release Merge
 -------------
 
 Release Merge
 -------------
 

-Runs:
-
-- sigul-install
-- sigul-configuration
-- checkout ref from taglist.log
-- applies the $PROJECT.bundle
-- signs, tags and pushes
-
-.. code-block:: bash
-
-   lftools nexus release --server $NEXUS_URL $STAGING_REPO
-
-
-:Template Name:
-    - {project-name}-releases-merge-{stream}
+:Template Name: {project-name}-release-merge

 
 :Comment Trigger: remerge
 
 :Required parameters:
 
     :build-node: The node to run build on.
 
 :Comment Trigger: remerge
 
 :Required parameters:
 
     :build-node: The node to run build on.

-    :jenkins-ssh-credential: Credential to use for SSH. (Generally set
+    :jenkins-ssh-release-credential: Credential to use for SSH. (Generally set

         in defaults.yaml)
         in defaults.yaml)

-    :stream: run this job against: master
+    :stream: run this job against: **

 
 :Optional parameters:
 
 
 :Optional parameters:
 

-    :branch: Git branch to fetch for the build. (default: master)
+    :branch: Git branch to fetch for the build. (default: all)

     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
     :project-pattern: Project to trigger build against. (default: \*\*)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
     :project-pattern: Project to trigger build against. (default: \*\*)


@@ -76,25 +211,14 @@ Runs:
         file modifications will trigger a build.
         **default**::
 
         file modifications will trigger a build.
         **default**::
 

-            - compare-type: ANT
-              pattern: 'releases/*.yaml'
+            - compare-type: REG_EXP
+              pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'

 
 
 Release Verify
 ------------------
 
 
 
 Release Verify
 ------------------
 

-Release verify job checks the schema and ensures that the staging-repo.txt.gz
-is available on the job.
-
-- sigul-install
-- sigul-configuration
-- checkout ref from taglist.log
-- applies the $PROJECT.bundle
-- signs and shows signature
-
-
-:Template Names:
-    - {project-name}-releases-verify-{stream}
+:Template Name: {project-name}-release-verify

 
 :Comment Trigger: recheck|reverify
 
 
 :Comment Trigger: recheck|reverify
 


@@ -103,11 +227,11 @@ is available on the job.
     :build-node: The node to run build on.
     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
         in defaults.yaml)
     :build-node: The node to run build on.
     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
         in defaults.yaml)

-    :stream: run this job against: master
+    :stream: run this job against: **

 
 :Optional Parameters:
 
 
 :Optional Parameters:
 

-    :branch: Git branch to fetch for the build. (default: master)
+    :branch: Git branch to fetch for the build. (default: all)

     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-node: The node to run build on.
     :build-timeout: Timeout in minutes before aborting build. (default: 15)
     :build-days-to-keep: Days to keep build logs in Jenkins. (default: 7)
     :build-node: The node to run build on.
     :build-timeout: Timeout in minutes before aborting build. (default: 15)


@@ -122,5 +246,5 @@ is available on the job.
         file modifications will trigger a build.
         **default**::
 
         file modifications will trigger a build.
         **default**::
 

-            - compare-type: ANT
-              pattern: 'releases/*.yaml'
+            - compare-type: REG_EXP
+              pattern: '(releases\/.*\.yaml|\.releases\/.*\.yaml)'