Merge pull request #37 from vivster7/viv/fetch-merge-ref-fallback

Add retries when pulling the merge refspec

Author: ivannalisetska

README.md

@@ -56,14 +56,32 @@ The cleanup removes `.git/config.worktree` and unsets `extensions.worktreeConfig
 
 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.
 
-##### `unshallow` ('true' or 'false')
+#### `unshallow` ('true' or 'false')
 
 Convert the shallow clone into a full-depth clone by running `git fetch --unshallow origin` after checkout. This is useful when your build requires full git history (for example, changelog generation, `git log`, or `git blame`). If the repository is already unshallow, this step is skipped.
 
+## Environment Variables
+
+### 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, 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.
+
+
 ## Example
 
 Below is an example of using sparse-checkout plugin.

hooks/checkout

@@ -30,6 +30,8 @@ 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="$(plugin_read_config MERGE_REF_RETRY_ATTEMPTS "3")"
+
 if [[ "${CLEAN_CHECKOUT_OPTION}" = "true" ]]; then
   log_warning "clean_checkout is enabled - this will destroy any local changes and reset the repository state"
 fi
@@ -98,27 +100,83 @@ fi
 
 FETCH_FLAGS+=(--depth 1 origin)
 
+FETCH_OUTPUT=""
+
+is_missing_merge_ref_error() {
+  local merge_ref="refs/pull/${BUILDKITE_PULL_REQUEST}/merge"
+  [[ "${FETCH_OUTPUT}" == *"couldn't find remote ref ${merge_ref}"* ]] \
+    || [[ "${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" ]] \
   && [[ -n "${BUILDKITE_PULL_REQUEST:-}" ]] \
   && [[ "${BUILDKITE_PULL_REQUEST}" != "false" ]]; then
   USE_MERGE_REFSPEC="true"
-  FETCH_FLAGS+=("refs/pull/${BUILDKITE_PULL_REQUEST}/merge")
-elif [[ ${BUILDKITE_COMMIT} = "HEAD" ]]; then
-  FETCH_FLAGS+=("${BUILDKITE_BRANCH}")
-else
-  FETCH_FLAGS+=("${BUILDKITE_COMMIT}")
-fi
+  MERGE_REF="refs/pull/${BUILDKITE_PULL_REQUEST}/merge"
 
-if [[ "${USE_MERGE_REFSPEC}" = "true" ]]; then
   log_info "Fetching merge ref for PR #${BUILDKITE_PULL_REQUEST} from origin"
-else
-  log_info "Fetching ${BUILDKITE_COMMIT} from origin"
+
+  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
+
+    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
+        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
-if ! git fetch "${FETCH_FLAGS[@]}"; then
-  log_error "Failed to fetch ${BUILDKITE_COMMIT} from origin"
-  exit 1
+
+if [[ "${USE_MERGE_REFSPEC}" != "true" ]]; then
+  if [[ ${BUILDKITE_COMMIT} = "HEAD" ]]; then
+    FETCH_FLAGS+=("${BUILDKITE_BRANCH}")
+  else
+    FETCH_FLAGS+=("${BUILDKITE_COMMIT}")
+  fi
+
+  log_info "Fetching ${BUILDKITE_COMMIT} from origin"
+  if ! git fetch "${FETCH_FLAGS[@]}"; then
+    log_error "Failed to fetch ${BUILDKITE_COMMIT} from origin"
+    exit 1
+  fi
 fi
 log_success "Fetch completed successfully"
 
@@ -144,5 +202,4 @@ else
     exit 1
   fi
 fi
-
 log_success "Sparse checkout completed successfully"

plugin.yml

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

tests/checkout.bats

@@ -185,6 +185,36 @@ setup() {
   unstub git
 }
 
+@test "Retries missing merge ref before succeeding" {
+  export BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC="true"
+  export BUILDKITE_PULL_REQUEST="123"
+  export BUILDKITE_COMMIT="abc123"
+
+  stub ssh-keyscan "* : echo 'keyscan'"
+  stub sleep \
+    "2 : true" \
+    "5 : true"
+  stub git \
+    "clean * : echo 'git clean'" \
+    "fetch --depth 1 origin refs/pull/123/merge : echo \"fatal: couldn't find remote ref refs/pull/123/merge\" >&2; exit 1" \
+    "fetch --depth 1 origin refs/pull/123/merge : echo \"fatal: couldn't find remote ref refs/pull/123/merge\" >&2; exit 1" \
+    "fetch --depth 1 origin refs/pull/123/merge : echo 'git fetch merge refspec'" \
+    "sparse-checkout set * * : echo 'git sparse-checkout'" \
+    "checkout FETCH_HEAD : echo 'checkout fetch_head'"
+
+  run "$PWD"/hooks/checkout
+
+  assert_success
+  assert_output --partial 'retrying in 2s'
+  assert_output --partial 'retrying in 5s'
+  assert_output --partial 'git fetch merge refspec'
+  assert_output --partial 'checkout fetch_head'
+
+  unstub sleep
+  unstub ssh-keyscan
+  unstub git
+}
+
 @test "Does not use merge refspec when BUILDKITE_PULL_REQUEST is false" {
   export BUILDKITE_PULL_REQUEST_USING_MERGE_REFSPEC="true"
   export BUILDKITE_PULL_REQUEST="false"