Update RTD to use Generic API v2 webhook

The old tokenless generic trigger url has been deprecated. Update
to using the new v2 API that requires a token.

This is a backwards incompatible change and modifies 2 things:

  * rtd-project is now the rtd-build-url parameter
  * rtd-token is a new required parameter

Issue: RELENG-879
Change-Id: I786240ab14cf95a2896d92d1c87aef9d7815d964
Co-Authored-By: Thanh Ha <thanh.ha@linuxfoundation.org>
Signed-off-by: Jeremy Phelps <jphelps@linuxfoundation.org>
Signed-off-by: Thanh Ha <thanh.ha@linuxfoundation.org>

diff --git a/.jjb-test/lf-rtd-jobs.yaml b/.jjb-test/lf-rtd-jobs.yaml
index 753803b..1f1f700 100644 (file)
--- a/.jjb-test/lf-rtd-jobs.yaml
+++ b/.jjb-test/lf-rtd-jobs.yaml
@@ -5,8 +5,9 @@
       - gerrit-rtd-merge
       - gerrit-rtd-verify
 
-    rtd-project: gerrit-rtd
     project-name: gerrit-rtd
+    rtd-build-url: fake-rtd-build-url
+    rtd-token: fake-rtd-token
 
 - project:
     name: github-rtd-jobs
@@ -14,5 +15,6 @@
       - github-rtd-merge
       - github-rtd-verify
 
-    rtd-project: github-rtd
     project-name: github-rtd
+    rtd-build-url: fake-rtd-build-url
+    rtd-token: fake-rtd-token

diff --git a/docs/jjb/lf-rtd-jobs.rst b/docs/jjb/lf-rtd-jobs.rst
index 8f85f1a..780fd62 100644 (file)
--- a/docs/jjb/lf-rtd-jobs.rst
+++ b/docs/jjb/lf-rtd-jobs.rst
@@ -44,7 +44,24 @@ Job Templates
 ReadTheDocs Merge
 -----------------
 
-Merge job which triggers a POST of the docs project to readthedocs
+Merge job which triggers a POST of the docs project to readthedocs.
+
+To use this job first configure the ``Generic API incoming webhook`` in
+ReadTheDocs. To do that follow these steps:
+
+#. Browse to https://readthedocs.org/dashboard/PROJECT/integrations/
+#. Click on ``Generic API incoming webhook``
+
+   .. note::
+
+      If not available click on ``Add integration`` and add the
+      ``Generic API incoming webhook``.
+
+#. Copy the custom webhook URL, this is your ``rtd-build-url``
+
+   For example: https://readthedocs.org/api/v2/webhook/opendaylight/32321/
+
+#. Copy the token, this is your ``rtd-token``
 
 :Template Names:
     - {project-name}-rtd-merge-{stream}
@@ -56,7 +73,12 @@ Merge job which triggers a POST of the docs project to readthedocs
     :build-node: The node to run build on.
     :jenkins-ssh-credential: Credential to use for SSH. (Generally set
         in defaults.yaml)
-    :rtd-project: This is the name of the project on ReadTheDocs.org.
+    :rtd-build-url: This is the generic webhook url from readthedocs.org. Refer
+        to the above instructions to generate one.
+        (Check Admin > Integrations > Generic API incoming webhook)
+    :rtd-token: The unique token for the project Generic webhook. Refer
+        to the above instructions to generate one.
+        (Check Admin > Integrations > Generic API incoming webhook)
 
 :Optional parameters:
 

diff --git a/jjb/lf-macros.yaml b/jjb/lf-macros.yaml
index fb24a62..c5fa0f4 100644 (file)
--- a/jjb/lf-macros.yaml
+++ b/jjb/lf-macros.yaml
@@ -185,7 +185,9 @@
     name: lf-rtd-trigger-build
     builders:
       - inject:
-          properties-content: RTD_PROJECT={rtd-project}
+          properties-content: |
+            RTD_BUILD_URL={rtd-build-url}
+            RTD_TOKEN={rtd-token}
       - shell: !include-raw-escape: ../shell/rtd-trigger-build.sh
 
 - builder:

diff --git a/jjb/lf-rtd-jobs.yaml b/jjb/lf-rtd-jobs.yaml
index 20470be..2b7ae8a 100644 (file)
--- a/jjb/lf-rtd-jobs.yaml
+++ b/jjb/lf-rtd-jobs.yaml
@@ -87,7 +87,8 @@
 
     builders:
       - lf-rtd-trigger-build:
-          rtd-project: '{rtd-project}'
+          rtd-build-url: '{rtd-build-url}'
+          rtd-token: '{rtd-token}'
 
 - job-template:
     name: '{project-name}-rtd-merge-{stream}'

diff --git a/shell/rtd-trigger-build.sh b/shell/rtd-trigger-build.sh
index 21e7269..673d0f9 100644 (file)
--- a/shell/rtd-trigger-build.sh
+++ b/shell/rtd-trigger-build.sh
@@ -8,16 +8,32 @@
 # which accompanies this distribution, and is available at
 # http://www.eclipse.org/legal/epl-v10.html
 ##############################################################################
+# Call cURL to trigger a build in RTD via the Generic API
+#
+# Paramters:
+#     RTD_BUILD_URL: The unique build URL for the project.
+#                    Check Admin > Integrations > Generic API incoming webhook.
+#
+#     RTD_TOKEN: The unique token for the project Generic webhook.
+#                Check Admin > Integrations > Generic API incoming webhook.
+
 echo "---> rtd-trigger-build.sh"
 
 # Ensure we fail the job if any steps fail.
-# DO NOT set -u
-set -xe -o pipefail
+# DO NOT set -u as we depend on unbound variables being passed by Jenkins.
+set -e -o pipefail
+
+# Ensure RTD_BUILD_URL retains the trailing slash as it is needed for the API
+last_char=${RTD_BUILD_URL:length-1:1}
+[[ $last_char != "/" ]] && RTD_BUILD_URL="$RTD_BUILD_URL/"; :
+
+json=$(curl -X POST -d "branches=${GERRIT_BRANCH}" -d "token=$RTD_TOKEN" "$RTD_BUILD_URL")
+build_triggered=$(echo $json | jq -r .build_triggered)
 
-if [ "$GERRIT_BRANCH" == "master" ]; then
-    RTD_BUILD_VERSION=latest
-else
-    RTD_BUILD_VERSION="${GERRIT_BRANCH/\//-}"
+if [ "$build_triggered" != "true" ]; then
+    echo "ERROR: Build was not triggered."
+    echo "$json" | jq -r
+    exit 1
 fi
 
-curl -X POST --data "version_slug=$RTD_BUILD_VERSION" "https://readthedocs.org/build/$RTD_PROJECT"
+echo "Build triggered for $GERRIT_PROJECT in ReadTheDocs."