YETUS-1060. github status should use htmlreport

asf-site-src/source/documentation/in-progress/precommit/plugins/github.html.md

@@ -41,8 +41,16 @@ None
 | `--github-api-url=<url>` | REST API URL (for GitHub Enterprise) |
 | `--github-base-url=<url>` | Non-REST API URL (for GitHub Enterprise) |
 | `--github-repo=<repo>` | `username/repository` identifier |
+| `--github-status-use-htmlreport=<bool>` | Use htmlout for Github Status 'Details' link |
 | `--github-token=<token>` | Token used to perform read and write operations |
 
+## HTML Details LInk
+
+By default, if Apache Yetus is under conditions when it would normally write a Github Status (e.g., Jenkins processing
+a GitHub PR using the Github Multibranch Plug-in), the Details will link to the [htmlout](../htmlout) report rather than
+the robot's console after the run is complete. The report file must either be relative to the normal `--patch-dir` or
+be forcibly set using the `--html-report-url`.
+
 # Docker Notes
 
 None

asf-site-src/source/documentation/in-progress/precommit/plugins/htmlout.html.md

@@ -39,6 +39,7 @@ None
 | Option | Notes |
 |:---------|:------|
 | `--html-report-file=<file>` | Name of the output file |
+| `--html-report-url=<url>` | Override the default URL for using the HTML report |
 
 # Docker Notes
 

precommit/src/main/shell/plugins.d/github.sh

@@ -40,6 +40,7 @@ GITHUB_STATUS_RECOVERY_COUNTER=1
 GITHUB_STATUS_RECOVER_TOOL=false
 GITHUB_WRITE_COMMENT=false
 GITHUB_ANNOTATION_LIMIT=50
+GITHUB_STATUS_USE_HTMLREPORT=${GITHUB_STATUS_USE_HTMLREPORT:-true}
 declare -a GITHUB_AUTH
 
 # private globals...
@@ -54,6 +55,7 @@ function github_usage
   yetus_add_option "--github-token=<token>" "The token to use to read/write to github"
   yetus_add_option "--github-write-comment" "Write final report as github comment (default: '${GITHUB_WRITE_COMMENT}')"
   yetus_add_option "--github-use-emoji-vote" "Whether to use emoji to represent the vote result on github [default: ${GITHUB_USE_EMOJI_VOTE}]"
+  yetus_add_option "--github-status-use-htmlreport=<bool>" "Use htmlout for Github Status 'Details' link [default: ${GITHUB_STATUS_USE_HTMLREPORT}]"
 }
 
 function github_parse_args
@@ -90,6 +92,10 @@ function github_parse_args
         delete_parameter "${i}"
         GITHUB_USE_EMOJI_VOTE=true
       ;;
+      --github-status-use-htmlreport=*)
+        delete_parameter "${i}"
+        GITHUB_STATUS_USE_HTMLREPORT=${i#*=}
+      ;;
     esac
   done
 }
@@ -184,6 +190,8 @@ function github_brute_force_repo_on_remote
 ## @description initialize github
 function github_initialize
 {
+  declare url
+
   if [[ -n "${GITHUB_TOKEN}" ]]; then
     GITHUB_AUTH=(-H "Authorization: token ${GITHUB_TOKEN}") # pragma: allowlist secret
   fi
@@ -208,6 +216,19 @@ function github_initialize
     fi
   fi
 
+  if [[ ${GITHUB_STATUS_USE_HTMLREPORT} == true ]]; then
+    if ! verify_plugin_enabled htmlout; then
+      GITHUB_STATUS_USE_HTMLREPORT=false
+      yetus_error "WARNING: Disabling --github-status-use-htmlreport. htmlout plug-in is not enabled."
+    else
+      url=$(htmlout_reportname)
+      if [[ -z ${url} ]]; then
+        GITHUB_STATUS_USE_HTMLREPORT=false
+        yetus_error "WARNING: Disabling --github-status-use-htmlreport. Artifacts URL does not resolve/report is not relative."
+      fi
+    fi
+  fi
+
   # if the default branch hasn't been set yet, ask GitHub
   if [[ -z "${PATCH_BRANCH_DEFAULT}"  && -n "${GITHUB_REPO}" && "${OFFLINE}" == false ]]; then
     if [[ ! -f "${PATCH_DIR}/github-repo.json" ]]; then
@@ -582,6 +603,7 @@ function github_end_checkrun
   declare tempfile="${PATCH_DIR}/ghcheckrun.$$.${RANDOM}"
   declare output="${PATCH_DIR}/ghcheckrun-final.json"
   declare conclusion
+  declare detailslink
 
   # don't need this under GHA
   if [[ "${ROBOTTYPE}" == 'githubactions' ]]; then
@@ -604,10 +626,18 @@ function github_end_checkrun
 
   finishdate=$(date +"%Y-%m-%dT%H:%M:%SZ")
 
+  # link to the html report if possible
+  if [[ ${GITHUB_STATUS_USE_HTMLREPORT} == true ]]; then
+    detailslink=$(htmlout_reportname)
+  else
+    detailslink="${BUILD_URL}${BUILD_URL_CONSOLE}"
+  fi
+
   {
     printf "{"
     echo "\"conclusion\":\"${conclusion}\","
     echo "\"status\": \"completed\","
+    echo "\"details_url\": \"${detailslink}\","
     echo "\"completed_at\": \"${finishdate}\""
     echo "}"
   } > "${tempfile}"
@@ -1054,6 +1084,7 @@ function github_finalreport
   declare ourstring
   declare -i i=0
   declare header
+  declare detailslink
 
   if [[ "${OFFLINE}" == true ]]; then
     return 0
@@ -1082,8 +1113,6 @@ function github_finalreport
 
   github_end_checkrun "${result}"
 
-  url=$(get_artifact_url)
-
   if [[ "${ROBOTTYPE}" ]]; then
     header="Apache Yetus(${ROBOTTYPE})"
   else
@@ -1112,21 +1141,28 @@ function github_finalreport
       ((i=i+1))
     done
 
+    # link to the html report if possible
+    if [[ ${GITHUB_STATUS_USE_HTMLREPORT} == true ]]; then
+      detailslink=$(htmlout_reportname)
+    else
+      detailslink="${BUILD_URL}${BUILD_URL_CONSOLE}"
+    fi
+
     # did not find any logs, so just give a simple success status
     if [[ ${foundlogs} == false ]]; then
       if [[ ${warnings} == false ]]; then
         # build our REST post
         {
           echo "{\"state\": \"success\", "
-          echo "\"target_url\": \"${BUILD_URL}${BUILD_URL_CONSOLE}\","
+          echo "\"target_url\": \"${detailslink}\","
           echo "\"description\": \"passed\","
           echo "\"context\":\"${header}\"}"
         } > "${tempfile}"
       elif [[ ${warnings} == true ]]; then
         # build our REST post
         {
           echo "{\"state\": \"success\", "
-          echo "\"target_url\": \"${BUILD_URL}${BUILD_URL_CONSOLE}\","
+          echo "\"target_url\": \"${detailslink}\","
           echo "\"description\": \"passed with warnings\","
           echo "\"context\":\"${header}\"}"
         } > "${tempfile}"
@@ -1143,6 +1179,7 @@ function github_finalreport
   # - failure w/log
   # - success w/warning log
 
+  url=$(get_artifact_url)
   i=0
   until [[ ${i} -eq ${#TP_VOTE_TABLE[@]} ]]; do
     ourstring=$(echo "${TP_VOTE_TABLE[${i}]}" | tr -s ' ')

precommit/src/main/shell/plugins.d/htmlout.sh

@@ -16,13 +16,16 @@
 
 add_bugsystem htmlout
 
+HTMLOUT_REPORTFILE_URL=""
+
 ## @description  Usage info for htmlout plugin
 ## @audience     private
 ## @stability    evolving
 ## @replaceable  no
 function htmlout_usage
 {
   yetus_add_option "--html-report-file=<file>" "Save the final report to an HTML-formated file"
+  yetus_add_option "--html-report-url=<url>" "Override the default URL for using the HTML report"
 }
 
 ## @description  Option parsing for htmlout plugin
@@ -41,6 +44,10 @@ function htmlout_parse_args
         delete_parameter "${i}"
         fn=${i#*=}
       ;;
+      --html-report-url=*)
+        delete_parameter "${i}"
+        HTMLOUT_REPORTFILE_URL=${i#*=}
+      ;;
     esac
   done
 
@@ -52,6 +59,16 @@ function htmlout_parse_args
       yetus_error "WARNING: cannot create HTML report file ${fn}. Ignoring."
     fi
   fi
+
+  if [[ -z "${HTMLOUT_REPORTFILE_URL}" ]]; then
+    filepath=$(yetus_relative_dir "${PATCH_DIR}" "${HTMLOUT_REPORTFILE}")
+    url=$(get_artifact_url)
+
+    if [[ "${filepath}" != "${HTMLOUT_REPORTFILE}" ]]; then
+      HTMLOUT_REPORTFILE_URL="${url}/${filepath}"
+      USER_PARAMS+=("--html-report-url=${HTMLOUT_REPORTFILE_URL}")
+    fi
+  fi
 }
 
 ## @description  Give access to the HTML report file in docker mode
@@ -60,23 +77,26 @@ function htmlout_parse_args
 ## @replaceable  no
 function htmlout_docker_support
 {
+  # if for some reason the report file is in PATCH_DIR, then if
+  # PATCH_DIR gets cleaned out we lose access to the file on the 'outside'
+  # so we put it into the workdir which never gets cleaned.
+
   if [[ -n ${HTMLOUT_REPORTFILE} ]]; then
     DOCKER_EXTRAARGS+=("-v" "${HTMLOUT_REPORTFILE}:${DOCKER_WORK_DIR}/report.htm")
     USER_PARAMS+=("--html-report-file=${DOCKER_WORK_DIR}/report.htm")
   fi
 }
 
-
 ## @description  Write out an HTML version of the final report to a file
 ## @audience     private
 ## @stability    evolving
 ## @replaceable  no
 ## @param        runresult
-function htmlout_finalreport
+function htmlout_report_writer
 {
   declare result=$1
+  declare commentfile=$2
   declare i
-  declare commentfile="${HTMLOUT_REPORTFILE}"
   declare comment
   declare vote
   declare ourstring
@@ -92,12 +112,6 @@ function htmlout_finalreport
 
   rm "${commentfile}" 2>/dev/null
 
-  if [[ -z "${HTMLOUT_REPORTFILE}" ]]; then
-    return
-  fi
-
-  big_console_header "Writing HTML to ${commentfile}"
-
   {
     echo "<table><tbody>"
 
@@ -283,3 +297,39 @@ function htmlout_finalreport
 
   printf "<p>This message was automatically generated.</p>" >> "${commentfile}"
 }
+
+
+## @description  Write out an HTML version of the final report to a file
+## @audience     private
+## @stability    evolving
+## @replaceable  no
+## @param        runresult
+function htmlout_finalreport
+{
+  declare result=$1
+
+  rm "${commentfile}" 2>/dev/null
+
+  if [[ -z "${HTMLOUT_REPORTFILE}" ]]; then
+    return
+  fi
+
+  big_console_header "Writing HTML to ${commentfile}"
+
+  htmlout_report_writer "${result}" "${HTMLOUT_REPORTFILE}"
+}
+
+## @description  Write out an HTML version of the final report to a file
+## @audience     private
+## @stability    evolving
+## @replaceable  no
+## @return       url or empty string
+function htmlout_reportname
+{
+  if [[ -n "${HTMLOUT_REPORTFILE_URL}" ]]; then
+    echo "${HTMLOUT_REPORTFILE_URL}"
+    return
+  fi
+
+  echo ""
+}

precommit/src/main/shell/robots.d/buildkite.sh

@@ -34,6 +34,8 @@ if [[ "${BUILDKITE}" == true ]] &&
   ROBOTTYPE=buildkite
   # shellcheck disable=SC2034
   BUILD_URL="${BUILDKITE_BUILD_URL}"
+  # shellcheck disable=SC2034
+  GITHUB_STATUS_USE_HTMLREPORT="false"
 
   # shellcheck disable=SC2034
   if [[ "${BUILDKITE_PULL_REQUEST}" == false ]]; then

precommit/src/main/shell/robots.d/githubactions.sh

@@ -46,6 +46,9 @@ if [[ "${GITHUB_ACTIONS}" == true ]] &&
   # shellcheck disable=SC2034
   GITHUB_REPO="${GITHUB_REPOSITORY}"
 
+  # shellcheck disable=SC2034
+  GITHUB_STATUS_USE_HTMLREPORT="false"
+
   if [[ "${GITHUB_EVENT_NAME}" == push ]]; then
     # shellcheck disable=SC2034
     PATCH_OR_ISSUE=""

precommit/src/main/shell/robots.d/jenkins.sh

@@ -30,6 +30,7 @@ if [[ -n "${JENKINS_URL}" && -n "${EXECUTOR_NUMBER}" ]] &&
   JENKINS_CUSTOM_HOMEDIR=false
   BUILDMODE=full
   USER_PARAMS+=("--empty-patch")
+  GITHUB_STATUS_USE_HTMLREPORT=true
 
   # if we are running in an Jenkins docker container
   # spawned by using agent, then there is a good chance