Investigation: doc-bot fetch step fails on zero-match wildcard refspec

[Claude]

Investigation only — no code changes. The Documentation Bot run on PR #25681 failed and did not open a PR in vaadin/docs.

Findings

• Failure point: job agent, step 6 Fetch additional refs for vaadin/docs — exits 1 in ~300 ms, before the Claude agent starts. All subsequent steps skipped.
• Command: git fetch origin --depth=1 '+refs/heads/doc-bot/*:refs/remotes/origin/doc-bot/*' against vaadin/docs.
• Root cause: the wildcard matches zero remote refs (vaadin/docs has no doc-bot/* branches — verified across all ~200 branches). git 2.55 on the runner treats a zero-match wildcard fetch as an error. Stderr is scrubbed because VAADIN_BOT_TOKEN is passed via http.extraheader, which is why the log looks empty.
• PR in vaadin/docs: none. No PR references vaadin/flow#25681; no doc-bot/* branch was pushed.

Why no fix in this branch

• Failure is in .github/workflows/doc-bot.md:100 (fetch: ['doc-bot/*']), compiled by gh-aw into doc-bot.lock.yml. The lock file is generated; hand-editing it would be overwritten on the next compile.
• This branch targets an unrelated Java fix (nested-jar token lookup, already merged as bbf4fb4). Bundling a workflow change here would violate minimal-scope conventions and needs sign-off from the doc-bot workflow owners.

Suggested follow-up (separate PR against doc-bot.md)

Make the fetch tolerate a zero-match wildcard, e.g.:

- name: Fetch additional refs for vaadin/docs
  run: |
    header=$(printf "x-access-token:%s" "${GH_AW_FETCH_TOKEN}" | base64 -w 0)
    git -C "${{ github.workspace }}/docs-repo" \
        -c "http.extraheader=Authorization: Basic ${header}" \
        fetch origin --depth=1 '+refs/heads/doc-bot/*:refs/remotes/origin/doc-bot/*' || true

or drop the pre-fetch entirely and let the agent create the branch fresh — the prior actions/checkout of main is sufficient for the doc-bot to branch from.

• Fixes [aw] Documentation Bot failed #25698

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[mshabarov]

@claude what do you suggest? Would "let the agent create the branch fresh" be better working solution?

[claude]

Claude finished @mshabarov's task in 1m 35s —— View job

---

Recommendation on the zero-match fetch fix

I read the source and the generated lock file. Short version: I'd go with the tolerant fetch (|| true / zero-match-safe), not "create the branch fresh." Dropping the fetch fixes the crash but quietly removes a feature.

Why the fetch exists (it's not just decoration)

fetch: ['doc-bot/*'] (.github/workflows/doc-bot.md:100) is documented right above it:

# `doc-bot/*` brings in the branch of an
# existing documentation pull request, which Phase 5b commits onto.

That branch is what powers the push-to-pull-request-branch safe-output (doc-bot.md:125-129): when a docs PR already exists for the same source PR (re-run, or the source PR gets more commits), the bot updates that PR instead of opening a second one.

Why "create the branch fresh" is the weaker option

fetch: ['doc-bot/*'] compiles into the identical Fetch additional refs step in two jobs:

• the agent job — doc-bot.lock.yml:495-500
• the safe-output/push job — doc-bot.lock.yml:1882-1888

The safe-output job fetches doc-bot/* precisely so the push handler has the existing branch locally to commit onto. So if you drop the pre-fetch to "branch fresh," you don't just change where the branch comes from — you remove the update-in-place path. The likely result on re-runs / multi-commit PRs is duplicate docs PRs rather than one that gets updated. That defeats the whole push-to-pull-request-branch block.

(Also worth noting: because that step is in both jobs, the zero-match crash isn't specific to updates — even a first-time create_pull_request would hit the zero-match fetch in the safe-output job. So the tolerant fetch is what actually makes the common case work, not just the update case.)

The catch with || true

The || true in the follow-up snippet is shown against the generated doc-bot.lock.yml, which gets overwritten on the next gh-aw compile. There's no || true knob on the fetch: checkout option today, so the real fix has to land at the source, one of:

1. Upstream in gh-aw (githubnext/gh-aw) — make a wildcard fetch: refspec tolerate zero matches (this is arguably a compiler bug: git 2.55 errors on zero-match wildcards). Cleanest long-term, benefits every workflow, keeps behavior intact.
2. Replace fetch: with a custom tolerant step in doc-bot.md (if gh-aw lets you author raw steps) that runs the same fetch with || true — a local workaround until (1) lands.

Bottom line

• Best: tolerant fetch, preferably fixed in gh-aw (option 1). Preserves idempotent docs-PR updates and fixes the crash everywhere the step is generated.
• Acceptable quick unblock: "branch fresh" only if the owners are fine losing update-in-place and accept possible duplicate docs PRs. Given the PRs are draft with if-no-changes: ignore and a 30-day expiry, duplicates aren't catastrophic — but it's a real behavior regression, not a free simplification.

So to your question directly: no, I don't think "create the branch fresh" is the better working solution — it's the simpler one, but it trades away the deduplication the workflow was designed to do.

On implementing it here

I can't make this change myself — it lives under .github/workflows/, which I don't have permission to modify, and it's out of scope for this branch (unrelated Java fix) per the minimal-scope convention. This needs a separate PR against doc-bot.md (or an upstream gh-aw issue) with sign-off from the doc-bot workflow owners, as #25698 notes.
· branch claude/fix-count-nested-jars-in-token-file-lookup