docs: reframe for dual GitLab + GitHub support by titouanmathis · Pull Request #124 · weareikko/code-review

titouanmathis · 2026-07-15T13:17:41Z

Reframes the documentation so the tool reads as a dual-platform code reviewer — GitLab merge requests and GitHub pull requests on the same engine, platform auto-detected — rather than a GitLab tool that also does GitHub. Docs only; no src/ or test changes, no version bump.

What changed

README.md
- Dual-platform tagline; platform auto-detection stated up front (GITHUB_ACTIONS ⇒ github; GITLAB_CI / CI_PROJECT_ID / CI_SERVER_URL ⇒ gitlab; --platform forces it).
- Requirements now cover both a GitLab CI merge-request context and a GitHub Actions pull_request context.
- GitHub section leads with the composite action (bundled checkout — checkout/fetch-depth inputs) as the primary path, then documents the reusable workflow with an explicit caveat: secrets: inherit only works within the same organization/enterprise; cross-org consumers must use the composite action (own secrets) or pass secrets explicitly.
- Artifacts/troubleshooting/summary wording generalized to MR/PR.
docs/configuration.md — new Platform detection section, --platform, and the GitHub environment (GITHUB_TOKEN, GITHUB_REPOSITORY, PR-number resolution, GITHUB_API_URL, GITHUB_SERVER_URL) alongside the GitLab variables; draft posting noted as GitLab-only; CODE_REVIEW_ namespacing generalized to both CIs.
docs/output-format.md — both transports (GitLab inline discussions + summary note; GitHub batched review + summary issue comment) and the footer/marker back-compat (gitlab-review: markers still read).
docs/{providers,skills,multi-stage-review,observability}.md — MR-only wording generalized to MR/PR where platform-agnostic; observability notes the retained gitlab_* OTel identifier naming and that GitLab-CI project attributes are absent on GitHub.

All action/workflow examples pinned to @0.8.2; package @weareikko/code-review, command code-review.

🤖 Generated with Claude Code

Present the tool as a dual-platform reviewer (GitLab merge requests and GitHub pull requests on the same engine) rather than a GitLab tool that also does GitHub: - README: dual-platform tagline and platform auto-detection; requirements cover both a GitLab CI MR context and a GitHub Actions pull_request context; the GitHub section leads with the composite action (bundled checkout) and documents the reusable workflow with an explicit cross-organization `secrets: inherit` caveat; artifacts/troubleshooting generalized to MR/PR. - docs/configuration.md: add the platform-detection rule, `--platform`, and the GitHub environment (GITHUB_TOKEN / GITHUB_REPOSITORY / PR-number resolution / GITHUB_API_URL) alongside the GitLab variables; note that `draft` posting is GitLab-only. - docs/output-format.md: describe both transports (GitLab inline discussions + summary note; GitHub batched review + summary issue comment) and the footer/marker back-compat. - docs/{providers,skills,multi-stage-review,observability}.md: generalize MR-only wording to MR/PR where platform-agnostic; note the retained `gitlab_*` OTel identifier naming. Pin all action/workflow examples to @0.8.2. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-15T13:20:25Z

Code Review

Risk: Low — This is a docs-only MR and the code paths it describes mostly line up with the implementation, but a few reference sections still describe the old summary format or GitLab-only behavior and should be corrected before relying on them as contracts.

Reframes the documentation around dual GitLab/GitHub support, updates the setup guidance for GitHub Actions, and generalizes several MR-only sections across the docs set. Most of the changes match the current implementation, but docs/output-format.md and docs/configuration.md still contain a few stale statements from the pre-dual-platform wording.

3 issues found:

suggestion (non-blocking) — docs/output-format.md:25 — Align summary skeleton with current reviewer output
suggestion (non-blocking) — docs/output-format.md:57 — Describe the summary commit footer accurately
suggestion (non-blocking) — docs/configuration.md:51 — Generalize CODE_REVIEW_POST_SUMMARY to GitHub too

Still open from earlier reviews (6 findings):

README.md:146 — issue: Reusable workflow cannot accept explicit secrets
docs/output-format.md:57 — note: Reviewed-commit footer is documented with wrong format
docs/configuration.md:33 — note: GITHUB_SERVER_URL is documented but unused
docs/output-format.md:57 — note: Reviewed-commit footer is not hidden
docs/output-format.md:53 — note: GitHub posting is not always atomic
docs/configuration.md:113 — note: GitHub draft note claims false atomicity

Review usage: 641,620 in (571,392 cached) / 6,853 out tokens — $0.4212 (cloudflare-ai-gateway/gpt-5.4, thinking: medium)

Reviewed by @weareikko/code-review v0.8.2 for commit 4f26ecd.

Previous review runs

Previous run archived 2026-07-16T07:28:02Z

Code Review

Risk: Low — no blocking issues; safe to merge aside from nits.

This MR reframes the docs around dual GitLab/GitHub support, updates the README and reference docs for platform detection and transports, and adds the changelog entry with examples pinned to 0.8.2. The final diff also intentionally omits the GITHUB_SERVER_URL row mentioned in the original description, matching the later self-review fix commit. Two stale statements still need cleanup: the summary-format section documents the retired layout, and the GitHub draft explanation still claims atomicity that the implementation no longer guarantees.

2 issues found:

note — docs/output-format.md:25 — Summary skeleton documents the retired format
note — docs/configuration.md:113 — GitHub draft note claims false atomicity

Still open from earlier reviews (5 findings):

README.md:146 — issue: Reusable workflow cannot accept explicit secrets
docs/output-format.md:57 — note: Reviewed-commit footer is documented with wrong format
docs/configuration.md:33 — note: GITHUB_SERVER_URL is documented but unused
docs/output-format.md:57 — note: Reviewed-commit footer is not hidden
docs/output-format.md:53 — note: GitHub posting is not always atomic

Review usage: 594,836 in (496,640 cached) / 7,757 out tokens — $0.4860 (cloudflare-ai-gateway/gpt-5.4, thinking: medium)

Reviewed by @weareikko/code-review v0.8.2 for commit 2c69f10.

Previous run archived 2026-07-15T14:50:45Z

Code Review

Risk: Low — no blocking issues; safe to merge aside from nits.

This change reframes the project docs around dual GitLab/GitHub support, adds platform-detection and GitHub configuration guidance, and generalizes the README and reference docs from MR-only to MR/PR wording. The overall direction matches the implementation, but docs/output-format.md now contains two concrete behavior mismatches in the newly added transport/footer descriptions.

1 issue found:

note — docs/output-format.md:53 — GitHub posting is not always atomic

Still open from earlier reviews (4 findings):

README.md:146 — issue: Reusable workflow cannot accept explicit secrets
docs/output-format.md:57 — note: Reviewed-commit footer is documented with wrong format
docs/configuration.md:33 — note: GITHUB_SERVER_URL is documented but unused
docs/output-format.md:57 — note: Reviewed-commit footer is not hidden

Review usage: 1,289,348 in (1,170,944 cached) / 12,160 out tokens — $0.7711 (cloudflare-ai-gateway/gpt-5.4, thinking: medium)

Reviewed by @weareikko/code-review v0.8.2 for commit f19c8a7.

Previous run archived 2026-07-15T14:45:51Z

Code Review

Risk: Medium — issues that should be addressed before merge.

This MR reframes the project documentation around dual GitLab/GitHub support, updates the setup examples, and generalizes MR-only wording across the reference docs. The platform-detection and transport explanations are clearer overall, but a couple of newly added documentation claims diverge from the current implementation.

3 issues found:

issue — docs/output-format.md:28 — Summary format no longer matches runtime
note — docs/configuration.md:33 — GITHUB_SERVER_URL is documented but unused
note — docs/output-format.md:57 — Reviewed-commit footer is not hidden

Still open from earlier reviews (2 findings):

README.md:146 — issue: Reusable workflow cannot accept explicit secrets
docs/output-format.md:57 — note: Reviewed-commit footer is documented with wrong format

Review usage: 1,264,321 in (1,143,808 cached) / 8,690 out tokens — $0.7176 (cloudflare-ai-gateway/gpt-5.4, thinking: medium)

Reviewed by @weareikko/code-review v0.8.2 for commit 01b3a71.

Previous run archived 2026-07-15T13:20:56Z

Code Review

Risk: Medium — issues that should be addressed before merge.

This MR reframes the project docs around dual GitLab merge request and GitHub pull request support, updates the GitHub Actions guidance, and generalizes several MR-specific references across the documentation set. It also pins the action and workflow examples to @0.8.2 and explains platform detection, posting behavior, and observability differences. A few reference sections still describe behavior the current repo does not expose, so the docs are not yet safe to treat as authoritative.

3 issues found:

issue — docs/output-format.md:28 — Summary skeleton no longer matches emitted output
issue — README.md:146 — Reusable workflow cannot accept explicit secrets
note — docs/output-format.md:57 — Reviewed-commit footer is documented with wrong format

Review usage: 877,666 in (778,240 cached) / 10,150 out tokens — $0.5954 (cloudflare-ai-gateway/gpt-5.4, thinking: medium)

Reviewed by @weareikko/code-review v0.8.2 for commit d4784c3.

github-actions · 2026-07-15T13:20:26Z

+It reads review settings from repo/org **variables** (`CODE_REVIEW_MODEL`, `CODE_REVIEW_DEPTH`, `CODE_REVIEW_THINKING_LEVEL`, `CODE_REVIEW_VERIFY_MODEL`) and provider credentials from **secrets** named with the `CODE_REVIEW_` prefix (e.g. `CODE_REVIEW_ANTHROPIC_API_KEY`), which the CLI's env shim de-prefixes for the provider. Optional `with:` inputs: `model` (overrides the `CODE_REVIEW_MODEL` variable), `version`, `node-version`, `working-directory`, `args`, and `runs-on`.

-Prefer to run the CLI directly (no composite action)? `GITHUB_TOKEN`, `GITHUB_REPOSITORY`, and the PR number are read straight from the Actions environment:
+> **Caveat — `secrets: inherit` is same-organization (or enterprise) only.** Organization secrets are **not** inherited across organizations, so this pattern only works when the caller repository lives in the same org (or enterprise) as `weareikko/code-review`. Cross-organization consumers must use the **composite action** above (which references their own secrets directly), or call the reusable workflow while passing the secrets explicitly via `secrets:` instead of `secrets: inherit`.


issue: Reusable workflow cannot accept explicit secrets

The reusable workflow in .github/workflows/code-review.yml declares workflow_call.inputs only and reads provider credentials from ${{ secrets.CODE_REVIEW_* }}. The secrets: alternative described here does not match that workflow contract, so either remove this setup path or add declared on.workflow_call.secrets entries for the supported secret names.

Confidence: medium.

_{Reviewed by @weareikko/code-review v0.8.2 for commit d4784c3.}

github-actions · 2026-07-15T13:20:26Z

+| Summary         | An upserted non-positional **MR note**       | An upserted **issue comment**                                                                                          |
+| Posting modes   | `direct` or `draft` (atomic bulk publish)    | Always a single batched review; `draft` has no effect                                                                  |
+
+The hidden fingerprint markers, the summary marker, and the reviewed-commit footer are all HTML comments that render identically on both platforms, so deduplication, summary upsert, and the commit-skip guard work the same way on each.


note: Reviewed-commit footer is documented with wrong format

The fingerprint markers and summary marker are hidden HTML comments, but the reviewed-commit footer is emitted as visible Markdown text (Reviewed by ... / ...), not a comment. Reword this sentence so readers do not treat the visible footer as another hidden marker.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit d4784c3.}

github-actions · 2026-07-15T13:20:57Z

+| `GITHUB_REPOSITORY`                           | `owner/repo` slug of the GitHub repository (default for `--github-repository`). Set automatically in GitHub Actions.                                                                                                                                                                                                                                                                                |
+| `GITHUB_EVENT_PATH` / `GITHUB_REF`            | Sources the CLI reads to resolve the pull-request number when `--pr` is absent: the event payload (`.pull_request.number`, else top-level `.number`), then a `refs/pull/<N>/merge` (or `/head`) ref. Set automatically in GitHub Actions.                                                                                                                                                           |
+| `GITHUB_API_URL`                              | GitHub REST API base (default for `--github-api-url`; defaults to `https://api.github.com`). GitHub Enterprise sets it to e.g. `https://ghe.example.com/api/v3`; set automatically in GitHub Actions.                                                                                                                                                                                               |
+| `GITHUB_SERVER_URL`                           | GitHub web base (default `https://github.com`); honored on GitHub Enterprise. Set automatically in GitHub Actions.                                                                                                                                                                                                                                                                                  |


note: GITHUB_SERVER_URL is documented but unused

resolveConfig() stores GITHUB_SERVER_URL in config.githubServerUrl, but no runtime path reads that field when building links, footers, or API requests. Enterprise users who set this variable will see no change, so either wire it into the GitHub runtime behavior or remove it from the public configuration docs.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit 01b3a71.}

github-actions · 2026-07-15T13:20:57Z

+| Summary         | An upserted non-positional **MR note**       | An upserted **issue comment**                                                                                          |
+| Posting modes   | `direct` or `draft` (atomic bulk publish)    | Always a single batched review; `draft` has no effect                                                                  |
+
+The hidden fingerprint markers, the summary marker, and the reviewed-commit footer are all HTML comments that render identically on both platforms, so deduplication, summary upsert, and the commit-skip guard work the same way on each.


note: Reviewed-commit footer is not hidden

The fingerprint markers and summary marker are HTML comments, but the reviewed-commit footer is rendered as visible Reviewed by ... markup. Reword this sentence so readers do not assume the footer is hidden metadata.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit 01b3a71.}

- Reusable workflow declares no workflow_call.secrets, so drop the bogus "pass secrets explicitly" cross-org path (composite action only). - The reviewed-commit footer is a visible line, not a hidden HTML comment (only the fingerprint/summary markers are hidden). - Remove the GITHUB_SERVER_URL row: it is resolved into config but never read at runtime. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-15T14:45:52Z

+
+|                 | **GitLab (merge request)**                   | **GitHub (pull request)**                                                                                              |
+| --------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Inline comments | One positional MR **discussion** per finding | One **batched PR review** (`event: COMMENT`) carrying all inline comments — atomic and free of per-comment rate limits |


note: GitHub posting is not always atomic

src/platforms/github.ts retries each comment as its own single-comment review when the batched review returns 422, and src/platforms/github.test.ts covers the partial-success path. This row should describe the batched review as the normal path, then note the 422 fallback can partially post surviving comments instead of guaranteeing all-or-nothing delivery.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit f19c8a7.}

The poster falls back to per-comment posting on a 422 (off-diff position), so drop the "atomic" claim in the transport table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-15T14:50:46Z

 `--thinking` controls extended thinking on the underlying agent. Thinking tokens are billed at the model's output token rate, so higher levels cost more — the `Review usage:` line and `review-usage.json` reflect that cost.

-`--posting-mode draft` creates GitLab draft notes for every fresh comment and publishes them atomically via `POST /draft_notes/bulk_publish`. The reviewer either appears fully on the MR or not at all, instead of leaking partial state if the job is interrupted. If a draft creation fails mid-flight, the run sweeps the partial drafts before reporting the failure; if the job is killed before that, the next run's orphan cleanup picks them up. Requires a GitLab version that exposes the `draft_notes` and `bulk_publish` endpoints (≥ 15.10) and a token whose user can own draft notes — keep `direct` for older self-hosted instances or restricted tokens. `bulk_publish` publishes _all_ of the current user's drafts on the MR, so use a dedicated bot account if multiple processes may share the token.
+`--posting-mode draft` is **GitLab-only** (on GitHub a batched PR review is already atomic, so the flag has no effect there). It creates GitLab draft notes for every fresh comment and publishes them atomically via `POST /draft_notes/bulk_publish`. The reviewer either appears fully on the MR or not at all, instead of leaking partial state if the job is interrupted. If a draft creation fails mid-flight, the run sweeps the partial drafts before reporting the failure; if the job is killed before that, the next run's orphan cleanup picks them up. Requires a GitLab version that exposes the `draft_notes` and `bulk_publish` endpoints (≥ 15.10) and a token whose user can own draft notes — keep `direct` for older self-hosted instances or restricted tokens. `bulk_publish` publishes _all_ of the current user's drafts on the MR, so use a dedicated bot account if multiple processes may share the token.


note: GitHub draft note claims false atomicity

GitHubPlatform.postComments() retries each comment as its own single-comment review after a batched 422, so GitHub posting can still succeed partially even though --posting-mode draft is ignored there. Saying GitHub is "already atomic" gives the wrong guarantee and now contradicts docs/output-format.md, which was updated in this PR to describe the per-comment fallback. Rewrite this sentence to state only that GitHub has no draft-then-publish flow.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit 2c69f10.}

GitHub has no draft-then-publish flow; the batched review is not guaranteed atomic (per-comment fallback on 422). Aligns with docs/output-format.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions · 2026-07-16T07:28:03Z

+| Summary         | An upserted non-positional **MR note**       | An upserted **issue comment**                                                                                                                                                                                                         |
+| Posting modes   | `direct` or `draft` (atomic bulk publish)    | A single batched review (per-comment fallback on a 422); `draft` has no effect                                                                                                                                                        |
+
+The hidden fingerprint markers and the summary marker are HTML comments, invisible in the rendered view; the reviewed-commit footer is a visible `<sub>` line (`Reviewed by … for commit <sha>.`) that the commit-skip guard parses. All render identically on both platforms, so deduplication, summary upsert, and the commit-skip guard work the same way on each.


suggestion (non-blocking): Describe the summary commit footer accurately

The commit-skip guard reads the footer from the upserted summary comment, and buildReviewedCommitFooter() emits that footer as plain text, not as a  line. Limit the  wording to the inline comment footer section, or explicitly distinguish the summary footer from the inline footer here.

Confidence: high.

_{Reviewed by @weareikko/code-review v0.8.2 for commit 4f26ecd.}

titouanmathis and others added 2 commits July 15, 2026 15:17

docs: add changelog entry for dual-platform docs reframe

01b3a71

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot reviewed Jul 15, 2026

View reviewed changes

docs: clarify GitHub batched review is not always atomic

2c69f10

The poster falls back to per-comment posting on a 422 (off-diff position), so drop the "atomic" claim in the transport table. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

github-actions Bot reviewed Jul 15, 2026

View reviewed changes

docs: drop false GitHub atomicity claim in posting-mode note

4f26ecd

GitHub has no draft-then-publish flow; the batched review is not guaranteed atomic (per-comment fallback on 422). Aligns with docs/output-format.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

titouanmathis merged commit 459fb73 into main Jul 16, 2026
3 checks passed

titouanmathis deleted the docs/dual-platform-reframe branch July 16, 2026 07:26

github-actions Bot reviewed Jul 16, 2026

View reviewed changes

titouanmathis mentioned this pull request Jul 16, 2026

chore: prepare release 0.8.3 #126

Merged

Uh oh!

Conversation

titouanmathis commented Jul 15, 2026

What changed

Uh oh!

github-actions Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review

Previous run archived 2026-07-16T07:28:02Z

Code Review

Previous run archived 2026-07-15T14:50:45Z

Code Review

Previous run archived 2026-07-15T14:45:51Z

Code Review

Previous run archived 2026-07-15T13:20:56Z

Code Review

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot Jul 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Jul 15, 2026 •

edited

Loading