tf-a-lts-docs-watcher: Add tf-a-lts-docs-watcher job

Triggers whenever a code change is merged into the lts branch
or a lts tag is created of the TF-A repository. Executes a webhook
to trigger the ReadTheDocs service to build a fresh copy of the
documentation for one or more branches. [1]

[1]: https://linaro.atlassian.net/browse/TFC-511

Signed-off-by: Arthur She <arthur.she@linaro.org>
Change-Id: I9ab6cdd5240d81ebe0659231d7b7721181d0f700
diff --git a/scripts/tf-a-lts-docs-watcher.sh b/scripts/tf-a-lts-docs-watcher.sh
new file mode 100755
index 0000000..45f93f5
--- /dev/null
+++ b/scripts/tf-a-lts-docs-watcher.sh
@@ -0,0 +1,62 @@
+#!/bin/bash
+set -ex
+
+echo "########################################################################"
+echo "    Gerrit Environment"
+env |grep '^GERRIT'
+echo "########################################################################"
+
+RTD_WEBHOOK_URL="https://readthedocs.org/api/v2/webhook/trustedfirmware-a/87181/"
+RTD_VER_API="https://readthedocs.org/api/v3/projects/trustedfirmware-a/versions/"
+RTD_WEBHOOK_SECRET_KEY=${RTD_WEBHOOK_SECRET}
+RTD_API_TOKEN=${RTD_API_TOKEN}
+
+new_tag=""
+refname=${GERRIT_REFNAME##*/}
+lts_branch=${refname}
+echo ${GERRIT_REFNAME} | grep -q "refs\/tags\/" && lts_branch=${refname%.*} && new_tag=${refname}
+
+function activate_version() {
+    version=$1
+    retry=0
+
+    status=$(curl -s -X PATCH -H "Content-Type: application/json" -H "Authorization: Token ${RTD_API_TOKEN}" \
+                -d "{\"active\": true}" ${RTD_VER_API}/${version}/ | jq .detail)
+
+    while [ "${status}" = "\"Not found.\"" ];
+    do
+        [ ${retry} -gt 5 ] && echo "RTD can not find the version: ${new_tag}" && exit 1
+        sleep 10
+	    status=$(curl -s -X PATCH -H "Content-Type: application/json" -H "Authorization: Token ${RTD_API_TOKEN}" \
+                 -d "{\"active\": true}" ${RTD_VER_API}/${version}/ | jq .detail)
+        retry=$((retry+1))
+    done
+}
+
+echo "Notifying ReadTheDocs of changes on: ${lts_branch}"
+build_trigger=$(curl -s -X POST -d "branches=${lts_branch}" -d "token=${RTD_WEBHOOK_SECRET_KEY}" ${RTD_WEBHOOK_URL} | jq .build_triggered)
+if [ "${build_trigger}" = "false" ]; then
+	# The branch might be new and hasn't been known by RTD, or hasn't been activated, or both
+    # we can trigger a build for the master branch to update all versions
+	echo "The branch ${lts_branch} has not been activated! Activate it!"
+    curl -s -X POST -d "branches=master" -d "token=${RTD_WEBHOOK_SECRET_KEY}" ${RTD_WEBHOOK_URL}
+    activate_version ${lts_branch}
+fi
+
+# Triggered by a new tag
+if [ -n "${new_tag}" ]; then
+    echo -e "\nNew release tag: ${new_tag}"
+    # Hide the current active and unhidden tags
+    old_tags=$(curl -s -H "Authorization: Token ${RTD_API_TOKEN}" "${RTD_VER_API}/?slug=${lts_branch}&type=tag&active=true" | \
+    		   jq -r '.results | map(select(.hidden == false) | .verbose_name) | .[]')
+    for t in ${old_tags};
+    do
+        echo "Hide old tag: ${t}"
+        curl -s -X PATCH -H "Content-Type: application/json" -H "Authorization: Token ${RTD_API_TOKEN}" \
+        	 -d "{\"hidden\": true}" ${RTD_VER_API}/${t}/
+    done
+    # Active the new version
+    echo "Active new version: ${new_tag}"
+    activate_version ${new_tag}
+fi
+
diff --git a/tf-a-lts-docs-watcher.yaml b/tf-a-lts-docs-watcher.yaml
new file mode 100644
index 0000000..a6c2d61
--- /dev/null
+++ b/tf-a-lts-docs-watcher.yaml
@@ -0,0 +1,43 @@
+- job:
+    name: tf-a-lts-docs-watcher
+    node: master
+    project-type: freestyle
+    concurrent: false
+    description:
+      Triggers whenever a code change is merged into the lts branch 
+      or a lts tag is created of the TF-A repository. Executes a webhook
+      to trigger the ReadTheDocs service to build a fresh copy of the 
+      documentation for one or more branches.
+    disabled: false
+    builders:
+    - shell:
+        !include-raw: scripts/tf-a-lts-docs-watcher.sh
+    properties:
+    - build-discarder:
+        days-to-keep: 60
+        num-to-keep: 10
+    triggers:
+    - gerrit:
+        silent: true
+        server-name: 'review.trustedfirmware.org'
+        projects:
+        - branches:
+          - branch-compare-type: REG_EXP
+            branch-pattern: 'lts-v.*'
+          - branch-compare-type: REG_EXP
+            branch-pattern: refs/tags/lts-v.*
+          project-compare-type: PLAIN
+          project-pattern: 'TF-A/trusted-firmware-a'
+        trigger-on:
+        - ref-updated-event
+    wrappers:
+    - timestamps
+    - credentials-binding:
+      - text:
+          credential-id: TF-A-RTD-API-TOKEN
+          variable: RTD_API_TOKEN
+      - text:
+          credential-id: Trusted_Firmware_ReadTheDocs_Token
+          variable: RTD_WEBHOOK_SECRET
+    publishers:
+    - workspace-cleanup