Make Github Run ID selection stricter, update docs

tools/rapids-download-conda-from-github

@@ -1,5 +1,5 @@
 #!/bin/bash
-# A utility script that downloads a conda artifact archive from Github Artifacts, unzips it,
+# Downloads a conda artifact archive from Github Artifacts, unzips it,
 # and returns the path to the directory where it was unzipped.
 # Positional Arguments:
 #   1) a string of "cpp" or "python" which determines which conda artifact

tools/rapids-download-from-github

@@ -1,6 +1,7 @@
 #!/bin/bash
-# A utility script that downloads an artifact from Github Artifacts, unzips it to a temporary directory,
+# Downloads an artifact from Github Artifacts, unzips it to a temporary directory,
 # and prints the location where it was unzipped.
+#
 # Positional Arguments:
 #   1) package name to download from Github Artifacts
 set -euo pipefail

tools/rapids-download-wheels-from-github

@@ -1,6 +1,7 @@
 #!/bin/bash
-# A utility script that downloads a wheel artifact archive from Github Artifacts, unzips it,
+# Downloads a wheel artifact archive from Github Artifacts, unzips it,
 # and returns the path to the directory where it was unzipped.
+#
 # Positional Arguments:
 #   1) a string of "cpp" or "python" which determines which wheel artifact
 #      should be downloaded

tools/rapids-github-run-id

@@ -1,7 +1,22 @@
 #!/bin/bash
-# A utility script that examines environment variables provided
-# by GitHub Actions to print out a Github Workflow Run ID where the expected artifact
-# should be.
+# Determines the GitHub Actions run ID to use in operations with the GitHub API.
+#
+# When environment variable GITHUB_RUN_ID is defined, just returns that value.
+# GITHUB_RUN_ID is set automatically on GitHub Actions.
+# ref: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables
+#
+# Otherwise, tries to determine a run ID based on other context in the environment.
+# Most of that is provided by 'rapids-prompt-local-repo-config', see that
+# script's docs for details.
+#
+# Where multiple run IDs match the supplied configuration, the most-recently-created one
+# is chosen.
+#
+# Additional environment variables recognized by 'rapids-github-run-id':
+#
+#   * RAPIDS_BUILD_WORKFLOW_NAME = Filename for the workflow that the run corresponds to.
+#                                  Defaults to 'pr.yaml' for RAPIDS_BUILD_TYPE="pull-request" and 'build.yaml' otherwise).
+#
 set -euo pipefail
 export RAPIDS_SCRIPT_NAME="rapids-github-run-id"
 
@@ -13,8 +28,8 @@ case "${RAPIDS_BUILD_TYPE}" in
       --branch "${RAPIDS_REF_NAME}" \
       --commit "${RAPIDS_SHA}" \
       --workflow "${RAPIDS_BUILD_WORKFLOW_NAME:-pr.yaml}" \
-      --json databaseId \
-      --jq '.[0] | .databaseId')}
+      --json 'createdAt,databaseId' \
+      --jq 'sort_by(.createdAt) | reverse | .[0] | .databaseId')}
     ;;
   branch)
     run_id=${GITHUB_RUN_ID:-$(rapids-retry --quiet gh run list \
@@ -23,22 +38,30 @@ case "${RAPIDS_BUILD_TYPE}" in
       --commit "${RAPIDS_SHA}" \
       --workflow "${RAPIDS_BUILD_WORKFLOW_NAME:-build.yaml}" \
       --event "push" \
-      --json databaseId \
-      --jq '.[0] | .databaseId')}
+      --json 'createdAt,databaseId' \
+      --jq 'sort_by(.createdAt) | reverse | .[0] | .databaseId')}
     ;;
   nightly)
+    # Notice that for nightly runs, this script intentionally does not return GITHUB_RUN_ID.
+    #
+    # In RAPIDS CI, projects often have 2 separate workflows for nightlies:
+    #
+    #   * build.yaml = builds and uploads packages
+    #   * test.yaml  = installs nightly packages and runs tests
+    #
+    # From GitHub's perspective, those are different "runs", with different IDs.
+    # GitHub Actions organizes artifacts by run ID.
     run_id=$(rapids-retry --quiet gh run list \
       --repo "${RAPIDS_REPOSITORY}" \
       --branch "${RAPIDS_REF_NAME}" \
       --commit "${RAPIDS_SHA}" \
       --workflow "${RAPIDS_BUILD_WORKFLOW_NAME:-build.yaml}" \
       --event "workflow_dispatch" \
-      --created "${RAPIDS_NIGHTLY_DATE}" \
-      --json databaseId \
-      --jq '.[0] | .databaseId')
+      --json 'createdAt,databaseId' \
+      --jq 'sort_by(.createdAt) | reverse | .[0] | .databaseId')
     ;;
   *)
-    rapids-echo-stderr "please pass a valid RAPIDS_BUILD_TYPE"
+    rapids-echo-stderr "RAPIDS_BUILD_TYPE must be one of [branch, nightly, pull-request]"
     exit 1
     ;;
 esac

tools/rapids-prompt-local-github-auth

@@ -1,4 +1,5 @@
 #!/bin/bash
+#
 # A utility script that prompts user to authenticate with GitHub in
 # local environments
 

tools/rapids-prompt-local-repo-config

@@ -1,6 +1,22 @@
 #!/bin/bash
-# A utility script that prompts user to setup repository information in
-# local environments
+# Sets environment variables reused by other scripts here to interact with
+# git, the GitHub API, and external artifact storage.
+#
+# If those variables are already defined when this script is called, it will not overwrite them.
+# If not, it prompts interactively for them.
+#
+# Variables:
+#
+#   * RAPIDS_BUILD_TYPE          = One of "branch", "nightly", or "pull-request".
+#   * RAPIDS_NIGHTLY_DATE        = Date in YYYY-MM-DD format, used to organize nightly uploads.
+#                                  If not provided, the current system time is used.
+#                                  Only used when `RAPIDS_BUILD_TYPE` is "nightly".
+#   * RAPIDS_REF_NAME            = Branch or tag (e.g. "branch-25.08" or "pull-request/1234")
+#   * RAPIDS_REPOSITORY          = Repository the run happened in, in {org}/{repo} format (e.g. "rapidsai/rmm")
+#   * RAPIDS_SHA                 = Commit SHA on the repository indicated by `RAPIDS_REPOSITORY`.
+#                                  If not provided, this script assumes it's being run from within that repo
+#                                  and checks the commit pointed to by HEAD.
+#
 
 if [ "${CI:-false}" = "false" ]; then
   rapids-echo-stderr "Local run detected."