Refactor merge-ref retries per review; add merge_ref_retry_attempts

- Add try_fetch_merge_ref helper and loop over MERGE_REF_RETRY_ATTEMPTS
- Default 3 attempts; validate numeric config and document in README/plugin.yml
- Keep 2s then 5s backoff between attempts; non-merge-ref errors still fail fast

Made-with: Cursor

Author: vivster7

README.md

@@ -42,6 +42,10 @@ Use this option for pipeline upload jobs that don't need to preserve local chang
 
 Enable verbose logging with bash execution tracing (`set -x`). This shows each command being executed and can help debug issues with ssh-keyscan, git operations, or other checkout problems. When enabled, you'll see detailed output including command arguments and any error messages from underlying tools.
 
+#### `merge_ref_retry_attempts` (integer)
+
+How many times to try fetching the GitHub pull-request merge ref (`refs/pull/<n>/merge`) when using merge-ref checkout (see `BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC` below). Defaults to `3`. Between attempts the hook waits 2 seconds after the first failure and 5 seconds after later failures. Set to `0` to skip merge-ref fetch attempts and fall back immediately.
+
 #### `post_checkout` (object)
 
 Options that run after the sparse checkout completes, in the `post-checkout` hook.
@@ -54,13 +58,11 @@ Convert the shallow clone into a full-depth clone by running `git fetch --unshal
 
 ### BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC
 When `BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC=true`, the plugin will retry the
-GitHub merge ref checkout if it sees the known "missing merge ref" failure:
-
-- retry after 2 seconds
-- retry after 5 seconds
-- if the merge ref is still unavailable, fall back to the normal non-merge-ref
-  target (`BUILDKITE_BRANCH` when `BUILDKITE_COMMIT=HEAD`, otherwise
-  `BUILDKITE_COMMIT`)
+GitHub merge ref checkout if it sees the known "missing merge ref" failure, up to
+`merge_ref_retry_attempts` times (default `3`). Between attempts it waits 2 seconds
+after the first failure and 5 seconds after subsequent failures. If the merge ref
+is still unavailable, it falls back to the normal non-merge-ref target
+(`BUILDKITE_BRANCH` when `BUILDKITE_COMMIT=HEAD`, otherwise `BUILDKITE_COMMIT`).
 
 This retry logic only applies to the specific merge-ref-not-ready error. Other
 `git fetch` failures still fail immediately.

hooks/checkout

@@ -30,6 +30,13 @@ fi
 SKIP_SSH_KEYSCAN_OPTION="$(plugin_read_config SKIP_SSH_KEYSCAN "false")"
 CLEAN_CHECKOUT_OPTION="$(plugin_read_config CLEAN_CHECKOUT "false")"
 
+MERGE_REF_RETRY_ATTEMPTS_RAW="$(plugin_read_config MERGE_REF_RETRY_ATTEMPTS "3")"
+if [[ "${MERGE_REF_RETRY_ATTEMPTS_RAW}" =~ ^[0-9]+$ ]]; then
+  MERGE_REF_RETRY_ATTEMPTS="${MERGE_REF_RETRY_ATTEMPTS_RAW}"
+else
+  MERGE_REF_RETRY_ATTEMPTS=3
+fi
+
 if [[ "${CLEAN_CHECKOUT_OPTION}" = "true" ]]; then
   log_warning "clean_checkout is enabled - this will destroy any local changes and reset the repository state"
 fi
@@ -106,6 +113,25 @@ is_missing_merge_ref_error() {
     || [[ "${FETCH_OUTPUT}" == *"not our ref ${merge_ref}"* ]]
 }
 
+# Try to fetch merge ref. Returns 0 on success, 1 if merge ref is missing (retry),
+# otherwise logs and exits with git's status.
+try_fetch_merge_ref() {
+  local merge_ref="$1"
+  if FETCH_OUTPUT=$(git fetch "${FETCH_FLAGS[@]}" "${merge_ref}" 2>&1); then
+    [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}"
+    return 0
+  else
+    local status=$?
+    [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}" >&2
+    if is_missing_merge_ref_error; then
+      return 1
+    else
+      log_error "Failed to fetch merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
+      exit "${status}"
+    fi
+  fi
+}
+
 # Determine if we should use the pull request merge refspec
 USE_MERGE_REFSPEC="false"
 if [[ "${BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC:-false}" = "true" ]] \
@@ -115,49 +141,32 @@ if [[ "${BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC:-false}" = "true" ]] \
   MERGE_REF="refs/pull/${BUILDKITE_PULL_REQUEST}/merge"
 
   log_info "Fetching merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
-  if FETCH_OUTPUT=$(git fetch "${FETCH_FLAGS[@]}" "${MERGE_REF}" 2>&1); then
-    [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}"
-  else
-    status=$?
-    [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}" >&2
-    if ! is_missing_merge_ref_error; then
-      log_error "Failed to fetch merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
-      exit "${status}"
-    fi
 
-    log_warning "Merge ref ${MERGE_REF} was not available yet; retrying in 2s"
-    sleep 2
-    if FETCH_OUTPUT=$(git fetch "${FETCH_FLAGS[@]}" "${MERGE_REF}" 2>&1); then
-      [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}"
-    else
-      status=$?
-      [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}" >&2
-      if ! is_missing_merge_ref_error; then
-        log_error "Failed to fetch merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
-        exit "${status}"
-      fi
+  fetch_succeeded=false
+  for ((attempt = 1; attempt <= MERGE_REF_RETRY_ATTEMPTS; attempt++)); do
+    if try_fetch_merge_ref "${MERGE_REF}"; then
+      fetch_succeeded=true
+      break
+    fi
 
-      log_warning "Merge ref ${MERGE_REF} was still not available; retrying in 5s"
-      sleep 5
-      if FETCH_OUTPUT=$(git fetch "${FETCH_FLAGS[@]}" "${MERGE_REF}" 2>&1); then
-        [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}"
+    if [[ "${attempt}" -lt "${MERGE_REF_RETRY_ATTEMPTS}" ]]; then
+      if [[ "${attempt}" -eq 1 ]]; then
+        log_warning "Merge ref ${MERGE_REF} was not available yet; retrying in 2s"
+        sleep 2
       else
-        status=$?
-        [[ -n "${FETCH_OUTPUT}" ]] && printf '%s\n' "${FETCH_OUTPUT}" >&2
-        if ! is_missing_merge_ref_error; then
-          log_error "Failed to fetch merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
-          exit "${status}"
-        fi
-
-        if [[ "${BUILDKITE_COMMIT}" = "HEAD" ]]; then
-          log_warning "Merge ref ${MERGE_REF} was still unavailable; falling back to branch ${BUILDKITE_BRANCH}"
-        else
-          log_warning "Merge ref ${MERGE_REF} was still unavailable; falling back to ${BUILDKITE_COMMIT}"
-        fi
-
-        USE_MERGE_REFSPEC="false"
+        log_warning "Merge ref ${MERGE_REF} was not available yet; retrying in 5s"
+        sleep 5
       fi
     fi
+  done
+
+  if [[ "${fetch_succeeded}" != "true" ]]; then
+    if [[ "${BUILDKITE_COMMIT}" = "HEAD" ]]; then
+      log_warning "Merge ref ${MERGE_REF} was still unavailable; falling back to branch ${BUILDKITE_BRANCH}"
+    else
+      log_warning "Merge ref ${MERGE_REF} was still unavailable; falling back to ${BUILDKITE_COMMIT}"
+    fi
+    USE_MERGE_REFSPEC="false"
   fi
 fi
 

plugin.yml

@@ -16,6 +16,9 @@ configuration:
     clean_checkout:
       type: boolean
       default: false
+    merge_ref_retry_attempts:
+      type: integer
+      default: 3
     verbose:
       type: boolean
       default: false