fix(sync-docs): diagnosable fetch + name the missing SOURCE_REPOS_TOKEN#69
Open
LukasWodka wants to merge 2 commits into
Open
fix(sync-docs): diagnosable fetch + name the missing SOURCE_REPOS_TOKEN#69LukasWodka wants to merge 2 commits into
LukasWodka wants to merge 2 commits into
Conversation
The sync has failed 13/13 runs, dying ~2s in with a bare 'gh: Not Found (HTTP 404)'. Root cause: SOURCE_REPOS_TOKEN is unset, so the fetch falls back to the docs-scoped GITHUB_TOKEN, which 404s on the first PRIVATE source (tracebloc-py-package). 'jq | while' ran in a subshell and 'set -e' killed it on the first source, hiding the other four and the reason. Harden the fetch step: - process substitution instead of 'jq | while', so the loop runs in this shell - fetch every source and collect failures instead of dying on the first - on failure, emit '::error::' naming the repo and the gh message; drop the truncated cache file so a partial file is never synced - when SOURCE_REPOS_TOKEN is unset, print the exact fix: create a fine-grained PAT with Contents:read on the private source repo(s) and add it as SOURCE_REPOS_TOKEN Still fails closed until the token exists (a private source must sync), but now says precisely why and which token. Verified the loop with a stubbed gh: public sources cache, the private one reports a named error, exit 1 with guidance. The token itself must be created by an admin — that is the actual unblock. Refs RFC-BACKEND-0008 D21, tracebloc/backend#1279.
Contributor
Author
|
👋 Heads-up — Code review queue is at 40 / 30 Above the WIP limit. The team convention is to review existing PRs before opening new work. Open PRs currently in Code review (oldest first):
Pull from review before opening new work. (This is a nudge from the kanban WIP check, not a block.) |
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
docs had no advance-deploy-env caller, so its kanban items never advanced to Prod when code shipped to main — feature tickets stranded. Adds the standard push-triggered caller the other repos have, so shipping auto-advances tickets. RFC-BACKEND-0008 board automation.
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why sync-docs has been red for two weeks
Every run dies ~2 seconds in with a bare
gh: Not Found (HTTP 404). Diagnosed:SOURCE_REPOS_TOKENis not set (verified — no repo or org secret).GITHUB_TOKEN, which is scoped to this repo.tracebloc-py-package, which is private → cross-repo read with thedocs-scoped token → 404.
jq | whileran in a subshell andset -ekilled it on that first source, hiding the other four(all public —
client,start-training,data-ingestors,model-zoowould sync fine).The API path and ref are correct. It's purely the token.
What this PR does
Hardens the fetch step so the failure is diagnosable, not cryptic: fetch every source, collect
failures, name the repo and the gh message on each, drop truncated cache files, and — when
SOURCE_REPOS_TOKENis unset — print the exact remediation. Still fails closed (a private sourcemust sync), but now tells you precisely why. Verified the loop with a stubbed
gh.The actual unblock — needs you (I can't mint a PAT)
Create a fine-grained PAT: resource owner
tracebloc, repository access limited totracebloc/tracebloc-py-package(the only private source), permission Contents: Read, nothingelse. Add it as an Actions secret named
SOURCE_REPOS_TOKENon this repo (or the org, scoped todocs). Once set, all five sources sync and the workflow goes green.
docsis exempt from the develop-only rule — mergeable tomaindirectly.Note
Low Risk
Changes are limited to GitHub Actions workflows (fetch error handling and a new reusable-workflow caller); no application runtime or data paths are modified.
Overview
Adds a new
advance-deploy-envworkflow that runs on pushes todevelop,staging,master, ormainand delegates totracebloc/.githubto advance each merged PR’s Deploy environment on the engineer kanban.Hardens the
sync-docsupstream fetch step so failures are actionable instead of a singlegh: Not Found. It now tries every configured source (process substitution keeps the loop in the main shell), records per-repo errors, removes partial cache files, and still exits non-zero if anything failed. WhenSOURCE_REPOS_TOKENis missing, it emits a workflow error that explains the privatetracebloc-py-packagesource needs a fine-grained PAT with Contents read, without leaking secret values.Reviewed by Cursor Bugbot for commit e533e85. Bugbot is set up for automated code reviews on this repo. Configure here.