Skip to content

docs(github): continue through GraphQL, raw, or git when REST is rate limited - #971

Draft
aivong-openhands wants to merge 1 commit into
mainfrom
github-skill-rate-limit-fallbacks
Draft

aivong-openhands wants to merge 1 commit into
mainfrom
github-skill-rate-limit-fallbacks

Conversation

@aivong-openhands

Copy link
Copy Markdown
Contributor

HUMAN:


AGENT:

This PR was created by an AI agent (OpenHands) on behalf of @aivong-openhands.

Why

An agent ran gh api repos/<owner>/<repo>/contents/<dir> and got HTTP 403: API rate limit exceeded. After some trial and error it found that a sparse git clone worked, because git over HTTPS does not use REST quota. The github skill had nothing about rate limits, so the agent had to work that out itself. This PR writes the order of steps into the skill so the agent reaches a working path straight away.

Waiting alone does not solve it. With a primary limit, x-ratelimit-reset can be up to an hour away (about 25 minutes in this case), and GitHub sends no retry-after. A second token of the same user does not help either, because the limit is per user.

Summary

  • skills/github/SKILL.md: new ## Rate limits section. The agent checks gh api rate_limit first (it uses no quota). It waits only for a secondary limit or a reset less than 5 minutes away. Otherwise it continues at once with GraphQL (separate quota), raw.githubusercontent.com, or git over HTTPS. It also says which gh subcommands still work and that another token of the same user does not help.
  • skills/github/README.md and references/windows.md: document the section, and add a curl.exe note for PowerShell 5.1.
  • skills/index.js: regenerated by node scripts/build-skills-catalog.mjs.
Before:  403 rate limit -> retry / improvise -> (eventually) git clone
After:   403 rate limit -> gh api rate_limit -> reset < 5 min ? wait
                                                  : GraphQL | raw | git (same token, no REST quota)

Issue Number

None.

How to Test

The REST core quota for the account was at 0 (reset 20:12:26 UTC). I ran every bash block of the new section exactly as written, replacing only the placeholders (OWNER=OpenHands, REPO=extensions, path/to/dir=skills/github, NUMBER=967). The script that did this (/tmp/run_skill_section.py) pulls the blocks from SKILL.md with a regex, so it tests the text an agent will see. The token is redacted.

2026-11-20T20:08:45Z

$ gh api rate_limit --jq '.resources | {core, graphql}'
{"core":{"limit":5000,"remaining":0,"reset":1795205546,"used":5000},"graphql":{"limit":5000,"remaining":4977,"reset":1795205734,"used":23}}
[exit 0]

$ gh api graphql -f owner=OpenHands -f name=extensions -f expr=main:skills/github -f query='query($owner:String!,$name:String!,$expr:String!){repository(owner:$owner,name:$name){object(expression:$expr){... on Tree{entries{path type}}}}}' --jq '.data.repository.object.entries[].path'
skills/github/.claude-plugin
skills/github/.codex-plugin
skills/github/.plugin
skills/github/README.md
skills/github/SKILL.md
skills/github/references
[exit 0]

$ curl -fsSL -H "Authorization: token $GITHUB_TOKEN" https://raw.githubusercontent.com/OpenHands/extensions/main/skills/github/README.md
# Github
...
[exit 0]

$ git clone -q --depth 1 --filter=blob:none --sparse https://github.com/OpenHands/extensions.git /tmp/extensions && git -C /tmp/extensions sparse-checkout set skills/github
[exit 0]

$ git clone -q --filter=blob:none --no-checkout https://github.com/OpenHands/extensions.git /tmp/extensions-pr && git -C /tmp/extensions-pr fetch -q origin pull/967/head:pr && git -C /tmp/extensions-pr diff origin/main...pr
diff --git a/skills/index.js b/skills/index.js
...
[exit 0]

core.remaining after run: 0

I also checked the claim about which gh subcommands still work, with the quota still at 0:

$ gh pr view 967 --repo OpenHands/extensions --json number,state   -> {"number":967,"state":"MERGED"}  [exit 0]
$ gh pr list --repo OpenHands/extensions --limit 1 --json number    -> [{"number":966}]                  [exit 0]
$ gh issue list --repo OpenHands/extensions --limit 1 --json number -> [{"number":970}]                  [exit 0]
$ gh pr checks 967 --repo OpenHands/extensions                      -> check table returned              (exit 1 = one check on that PR failed)
$ gh pr diff 967 --repo OpenHands/extensions                        -> HTTP 403: API rate limit exceeded [exit 1]

The failing REST call returned 403 with X-Ratelimit-Remaining: 0 and X-Ratelimit-Reset, and no Retry-After. That matches step 3 of the new section.

Repository checks:

  • uv run --group test pytest -q: 1654 passed, 33 skipped.
  • python scripts/sync_extensions.py --check: no errors. It shows two non-blocking coverage warnings for plugins that were already there.

Video/Screenshots

Not applicable (documentation change). The terminal logs above are the evidence.

Notes

  • Related: OpenHands/extensions-private#219 retires the private github-resilience skill. That skill's only answer to a primary limit was to sleep until the reset.
  • I did not test the commands from a Windows shell. The GraphQL one-liner uses variables, so the query has no embedded double quotes and needs no PowerShell here-string.

When a GitHub call fails with a rate-limit error, tell the agent to check
`gh api rate_limit` (no quota cost), wait only for secondary limits or a
reset under 5 minutes, and otherwise continue at once through paths that do
not use REST quota: GraphQL, raw.githubusercontent.com, or git over HTTPS.
Warn that another token of the same user shares the same quota.

Regenerate skills/index.js and add a PowerShell note for curl.exe.

Co-authored-by: openhands <openhands@all-hands.dev>
@aivong-openhands aivong-openhands changed the title github skill: continue through GraphQL, raw, or git when REST is rate limited docs(github): continue through GraphQL, raw, or git when REST is rate limited Nov 20, 2026
@github-actions github-actions Bot added the type: docs Documentation only changes label Nov 20, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: docs Documentation only changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant