Skip to content

fix(github-sync): surface GitHub's actual error instead of a bare 502 - #40

Merged
rubenvdlinde merged 3 commits into
developmentfrom
fix/surface-github-errors
Jul 27, 2026
Merged

rubenvdlinde merged 3 commits into
developmentfrom
fix/surface-github-errors

Conversation

@rubenvdlinde

Copy link
Copy Markdown
Contributor

Diagnosing a failed publish currently gives an operator 502 github_unreachable and nothing else, because the two places that know what went wrong both discard it.

What was hidden

  • brokerJson() catches the broker exception and logs it at debug. The fleet runs loglevel 2 deliberately (a debug-level run once filled a disk), so in practice that message does not exist.
  • A non-2xx upstream response was not logged at all, and its body — where GitHub puts a precise, actionable message — was dropped entirely.

Both now log at warning with method, path, status and a body prefix.

403 is not a transport failure

brokerFailureOutcome() folded every non-denied failure into github_unreachable → HTTP 502. A 403 is a permissions answer; calling it "unreachable" sends the reader at the network. Now mapped to a dedicated github_forbidden outcome → HTTP 403.

Why this is worth the small change

Real case that prompted it: publishing a file map containing .github/workflows/* requires a credential with the workflow permission, and GitHub answers

403 {"message":"Resource not accessible by personal access token",
     "documentation_url":".../rest/git/trees#create-a-tree"}

With the old reporting that surfaced as "GitHub unreachable" — while GET /user, GET /repos/{o}/{r}, GET/PATCH on refs, POST /git/blobs and even POST /git/trees with a small tree all demonstrably returned 200/201 through the same broker and credential. Six successful reachability checks against a "GitHub is unreachable" error is a long way to walk for a message GitHub had already spelled out.

Adding the warning log is what turned that into a one-line diagnosis.

Scope

No behaviour change on the success path — verified against a live instance: wizard → link → push still returns 200 {"outcome":"ok", commitSha, branch} with the commit landing on GitHub.

Note on #35

I filed #35 claiming wizard-created apps could not be pushed. That headline was wrong and I have corrected it there: the instance I diagnosed against was carrying an unmerged scaffoldFor() fold-in of my own that adds the 72-file scaffold (including the workflows) to the published map. On shipped development the push emits the 3-file config triad, contains no workflows, and works. The logging and 403-mapping improvements in this PR stand on their own; the "cannot push" claim does not.

A wizard-generated app failed `npm run build` out of the box, so every repo
OpenBuild published was uninstallable. Three separate causes, each verified by
running a real build of the emitted 72-file scaffold.

1. `terser-webpack-plugin` was declared by nobody. `@nextcloud/webpack-vue-config`
   requires it but does not depend on it and does not list it as a peer, so
   nothing installed it and webpack could not even start:
   `[webpack-cli] Error: Cannot find module 'terser-webpack-plugin'`.

2. `@nextcloud/axios@2.6.0` DROPPED its `require` export condition — a breaking
   change shipped as a minor bump. `@nextcloud/vue`'s CJS build require()s it, so
   the caret range `^2.5.0` floated into an unusable pair and webpack reported 14
   copies of:
   `"." is not exported under the conditions ["require", …] from @nextcloud/axios`.
   Pinning the direct dependency is NOT enough — npm nests its own copy under
   `@nextcloud/vue`, which is the copy that actually breaks — so this needs an
   `overrides` entry to apply transitively. 2.5.2 still ships `./dist/index.cjs`.

3. `@conduction/nextcloud-vue` bundles a `@nextcloud/dialogs` chunk that reaches
   for Node's `path`. Webpack 5 stopped auto-polyfilling core modules, so the
   browser build could not resolve it. Mapping just `path` to `path-browserify`
   rather than adding a blanket node-polyfill plugin: it is the only core module
   the dependency touches, and a blanket polyfill grows every generated app's
   bundle for nothing.

Verified end to end on the emitted scaffold: `npm install` (1321 packages) then
`npm run build` goes from **14 errors → 1 → 0**, producing real bundles. Only
the pre-existing entrypoint-size warnings remain.

Worth a CI guard: generate an app and run `npm ci && npm run build`. All three
defects are invisible to any test that stops at "the files were generated".

Fixes #38.
Diagnosing a failed publish currently gives an operator `502 github_unreachable`
and nothing else, because the two places that know what went wrong both discard
it:

- `brokerJson()` catches the broker exception and logs it at `debug`. The fleet
  runs `loglevel 2` deliberately (after a debug-level run once filled a disk),
  so in practice that message does not exist.
- A non-2xx upstream response was not logged at all, and its body — which is
  where GitHub puts a precise, actionable message — was dropped on the floor.

Both now log at `warning` with method, path, status and a body prefix.

Also maps HTTP 403 to a dedicated `github_forbidden` outcome (→ HTTP 403)
instead of folding it into `github_unreachable` (→ 502). A 403 is a permissions
answer, not a transport failure, and calling it "unreachable" sends the reader
at the network. The case that prompted this: publishing a file map containing
`.github/workflows/*` needs a credential with the `workflow` permission, and
GitHub answers `403 Resource not accessible by personal access token`. With the
old reporting that surfaced as "GitHub unreachable" while `GET /user`,
`GET /repos/…`, ref reads/writes and blob creation all demonstrably worked.

No behaviour change on the success path.
development gained the libxmljs2 security pin alongside the axios one while
this branch was open; this branch still carried the version that dropped it.
Keep development's.
@rubenvdlinde
rubenvdlinde merged commit 0a92231 into development Jul 27, 2026
2 checks passed
@rubenvdlinde
rubenvdlinde deleted the fix/surface-github-errors branch July 27, 2026 21:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants