Fix the API references workflow for XMLDoc2Markdown 6

[Laurianti]

The "Update API references" workflow fails on every approval, so docs/xmldocs has not been regenerated since October 2025.

Two problems:

1. dotnet tool install -g XMLDoc2Markdown installs 6.0.0, whose command is xmldoc2md and which needs .NET 10. The workflow runs dotnet xmldoc2md with .NET 8 only.
2. On a review, actions/checkout checks out the pull request's merge ref, not a branch, so git push has nowhere to go. On a pull request from a fork it cannot push at all: the job gets no write access to the fork.

So the docs are now regenerated after a merge into master, when LLama/ changes. That works whatever the pull request came from.

Before	Now
dotnet-xmldoc2md does not exist	Generation: 146 succeeded, 0 failed
on approval, push fails	after the merge, the docs commit lands on master

The contributing guide had the same dotnet xmldoc2md command, fixed too.

XMLDoc2Markdown 6 also writes a page for each fixed buffer type the compiler generates, such as llama.native.llamamodelmetadataoverride.<key>e__fixedbuffer.md. Windows cannot check out a name with < and >, so the job deletes those two pages and their lines in index.md. 5.0.0 is not an option: it fails to load Microsoft.Extensions.AI.Abstractions 10.

Checked on a GitHub runner in a private copy of master: a merged pull request starts the job, the docs commit lands on master, and it does not start the job again.

master is protected: REPO_TOKEN is used for the push when it is set. I cannot see whether it may push to master.

[Copilot]

Copilot review overview

🟡 Changes recommended

The workflow push target and contributor documentation still need updates.

Review effort: Lite
Findings: 1

Open (1)

• Push explicitly to a branch from the detached pull request ref · New

What changed in this PR

Updates the API-reference workflow for XMLDoc2Markdown 6 and .NET 10.

Changes:

• Adds .NET 10 setup.
• Invokes xmldoc2md directly.

File	Summary
.github/​workflows/​update_api_references.yml	Workflow invocation and runtime updated. Critical: configure an explicit push target for pull-request review runs. Nit: update the contributor documentation command.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[martindevans]

Thanks for investigating this!

[martindevans]

Unfortunately it doesn't look like this fixed it. It looks like the checkout action is failing, if you're interested in debugging it any more.

[Laurianti]

Thanks for checking. The checkout fails because it now uses secrets.REPO_TOKEN, and GitHub rejects that token: could not read Username is what git prints when the credentials are refused. Before #1443 the token was only used by the final push, which the workflow never reached, so this went unnoticed; my test repo had no such secret, so it fell back to github.token.

Two ways out:

• refresh the REPO_TOKEN secret, or
• drop it: check out with the default github.token and give the job permissions: contents: write. That works as long as the protection on master lets GitHub Actions push.

I can open a PR for the second one if you prefer it.

[martindevans]

Unfortunately I don't think I have access to refresh the REPO_TOKEN (I maintain the repo these days, but I didn't create it, so I don't have all the permissions). A PR for option #2 would be appreciated :)

[Laurianti]

Opened #1453 for option 2, with fallbacks from best to worst: the job first pushes the docs to master; if master refuses the push (it looks like it only takes pull requests: all but one of its last 400 commits came through one), it pushes them to their own branch and opens a pull request from it; if GitHub Actions is not allowed to open pull requests, it leaves the link to open one by hand. I tested each of these on a private copy and on a protected branch of my public fork. Once we see it run here, we can keep only the path that works and drop the others. What do you think?