{"record":{"id":"c9323c3e8b6586ba","repo":"666ghj/MiroFish","slug":"github-cli-gh-is-required-for-backfill","errorCode":null,"errorMessage":"GitHub CLI (gh) is required for backfill","messagePattern":"GitHub CLI \\(gh\\) is required for backfill","errorType":"exception","errorClass":"StarHistoryError","httpStatus":null,"severity":"error","filePath":"scripts/star_history.py","lineNumber":206,"sourceCode":"\nclass SystemClock:\n    def now(self) -> datetime:\n        return datetime.now(UTC).replace(microsecond=0)\n\n\nclass SubprocessCommandRunner:\n    def run(self, arguments: Sequence[str]) -> subprocess.CompletedProcess[str]:\n        try:\n            return subprocess.run(\n                list(arguments),\n                check=False,\n                capture_output=True,\n                text=True,\n                encoding=\"utf-8\",\n                timeout=45,\n            )\n        except FileNotFoundError as exc:\n            raise StarHistoryError(\"GitHub CLI (gh) is required for backfill\") from exc\n        except subprocess.TimeoutExpired as exc:\n            raise StarHistoryError(\"GitHub GraphQL request timed out\") from exc\n\n\nclass GhGraphQLGateway:\n    \"\"\"Production adapter for the one-time, maintainer-authorized backfill.\"\"\"\n\n    def __init__(self, runner: CommandRunner | None = None) -> None:\n        self._runner = runner or SubprocessCommandRunner()\n\n    def fetch_stargazer_page(self, after: str | None) -> StargazerPage:\n        arguments = [\n            \"gh\",\n            \"api\",\n            \"graphql\",\n            \"-f\",\n            f\"query={GRAPHQL_QUERY}\",\n            \"-f\",","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/scripts/star_history.py#L188-L224","documentation":"Raised by SubprocessCommandRunner.run when subprocess.run raises FileNotFoundError while launching the gh command — the GitHub CLI executable is not installed or not on PATH for the process running scripts/star_history.py. The backfill path shells out to `gh api graphql`, so gh is a hard runtime dependency for the one-time backfill command.","triggerScenarios":"Running `star_history.py backfill` on a machine/container without the gh binary; PATH not including gh in CI, cron, or a service context; gh installed via homebrew but the script runs under a different user/environment.","commonSituations":"Fresh CI image without gh; local dev on a machine that only has hub or git; systemd/cron jobs with minimal PATH; gh installed for the interactive user but the script runs as root.","solutions":["Install GitHub CLI: brew install gh (macOS), apt install gh / conda install gh (Linux), winget install GitHub.cli (Windows), then verify `gh --version`.","If gh is installed but not found, fix PATH for the executing context (export PATH=\"$PATH:/usr/local/bin\" or add it to the unit/cron environment).","Authenticate once before backfill: gh auth login (or set GH_TOKEN), since gh api needs credentials.","Remember only the backfill subcommand needs gh — scheduled updates use the credential-free fetch_star_count helper."],"exampleFix":"# before: CI job assumes gh exists\n- run: python scripts/star_history.py backfill\n\n# after: install and auth explicitly\n- run: |\n    python scripts/star_history.py backfill\n  env:\n    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n# plus a setup step: sudo apt-get install -y gh  (or use ghcli/setup-gh action)","handlingStrategy":"validation","validationCode":"import shutil\n\nif shutil.which(\"gh\") is None:\n    raise SystemExit(\n        \"GitHub CLI not found. Install it (brew/apt install gh) and \"\n        \"ensure it is on PATH before running backfill.\"\n    )\nsubprocess.run([\"python\", \"scripts/star_history.py\", \"backfill\"], check=True)","typeGuard":null,"tryCatchPattern":"try:\n    run_backfill()\nexcept StarHistoryError as exc:\n    if \"GitHub CLI (gh) is required\" in str(exc):\n        raise SystemExit(\"install gh and re-run: brew install gh && gh auth login\")\n    raise","preventionTips":["Check shutil.which('gh') in wrapper scripts before invoking backfill.","Install gh in CI images explicitly and run `gh auth status` as a preflight.","Remember only backfill needs gh; the scheduled credential-free path uses fetch_star_count.py."],"tags":["github-cli","subprocess","dependency","path","star-history"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}