docs: GitHub App install section + Marketplace-compliant action description#97
docs: GitHub App install section + Marketplace-compliant action description#97jadoonf wants to merge 6 commits into
Conversation
Co-Authored-By: Farrukh Jadoon <fkjadoon94@gmail.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
…E table cosmetics Co-Authored-By: Farrukh Jadoon <fkjadoon94@gmail.com>
|
Note for team: this will include some other cosmetic changes so we can align that at once |
devin-ai-integration
Bot
changed the title
Co-Authored-By: Farrukh Jadoon <fkjadoon94@gmail.com>
Co-Authored-By: Farrukh Jadoon <fkjadoon94@gmail.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| description: "Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRsreview. | ||
|
|
||
| " |
There was a problem hiding this comment.
🔍 Old description was more informative than the replacement
The previous description at action.yaml:2 clearly stated what the action does: "Records what each job in your workflow did at runtime — processes and network egress — and posts the Runtime Review from the Action stage." The new description is more marketing-oriented ("Execution evidence for code review...") but loses specificity about processes, network egress, and the Runtime Review posting behavior. Since this text appears in the GitHub Marketplace listing, it may be worth ensuring the replacement conveys the same functional information.
Was this helpful? React with 👍 or 👎 to provide feedback.
jadoonf
left a comment
jadoonf
left a comment
There was a problem hiding this comment.
Automated review-assist (agent-generated, advisory — not an approval or block).
Verified: action.yaml:2 new description is 117 chars (≤ 125 Marketplace limit) and matches actual behavior; name: is untouched (main already carries "Garnet Runtime Review", so no collision with #82's rename — that hunk of #82 is stale); README L109 install link uses the new App slug garnet-runtime-review (live; apps/garnet-platform 404s). The diff adds no comment-shape example blocks, so nothing here freezes pre-v6.1 shapes for the ENG-1355 renderer port — overlap with that PR is low.
Findings:
- README.md:111-118 (blocker): "Two permissions, nothing else" / "no webhook events" doesn't match the live App, which requests
actions:read,metadata:read,pull_requests:write,workflows:writeand subscribes toworkflow_job+workflow_run. Installers will see four permissions. Trimming first (as the PR body proposes) needs control-plane sign-off:service/event_processors.goreferences a workflow_run-webhook comment flow andserver/github_webhook.gois a live (no-op today) receiver, so those grants may be reserved for planned coverage work. - README.md:109: "Settings → GitHub in app.garnet.ai" — garnet-ui's install button still links the old slug (
app/(dashboard)/settings/github-settings-card.tsx:159,169-170→apps/garnet-platform[-dev], now 404). Needs the cross-repo fix or this install path dead-ends. - README.md:115,118 (minor): "one … comment per commit" is correct today; the v6.1 contract converges on one canonical comment per PR across commits — expect a wording pass after the port lands.
- Nit: PR body says the link is
apps/garnet-platform; the diff correctly usesapps/garnet-runtime-review. - vs #82: this supersedes #82's description rewrite. #82's only remaining unique bits:
author:field, SHA-pin example (stale at v2.1.0), alternate-install section. Consider cherry-pickingauthor:here and closing #82 (it's conflicting).
CI: Build/dist verify ✅; smoke jobs skipped (docs-only). Mergeable once (1) is resolved; timing is independent of the v6.1 port.
| description: "Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRs. | ||
|
|
||
| " |
There was a problem hiding this comment.
🟡 Action description contains an accidental trailing newline from malformed multi-line YAML
The action's description field includes an unintended trailing newline character (action.yaml:2-4) due to the closing quote being placed on a separate line after a blank line, so the metadata shown in the GitHub Marketplace or action listings may display with extra whitespace.
Impact: The action description displayed in GitHub Marketplace and workflow editor may show trailing whitespace or a blank line.
Multi-line YAML scalar produces trailing newline
The old description at action.yaml:2 was a clean single-line string:
description: "Records what each job in your workflow did at runtime ..."The new description spans lines 2-4:
description: "Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRs.
"When parsed by a YAML parser, this produces the string 'Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRs.\n' — note the trailing \n. The blank line between the text and the closing " on line 4 introduces this newline. The previous description had no trailing newline.
| description: "Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRs. | |
| " | |
| description: "Execution evidence for code review: what each CI job ran and reached, recorded at the kernel, posted on your PRs." | |
Was this helpful? React with 👍 or 👎 to provide feedback.
| Install the [Garnet Runtime Review GitHub App](https://github.com/apps/garnet-runtime-review) on the repos you monitor, or from Settings → GitHub in [app.garnet.ai](https://app.garnet.ai). | ||
|
|
||
| Two permissions, nothing else: | ||
|
|
||
| | Permission | Access | Why | | ||
| | ---------- | ------ | --- | | ||
| | Pull requests | Read & write | Post and update the one Runtime Review comment per commit | | ||
| | Metadata | Read | Required for every GitHub App | | ||
|
|
||
| The App writes the comment and does nothing else — no webhooks, no code access. Once installed it owns the comment across every recorded job on the commit, and the Action stands down. |
There was a problem hiding this comment.
🔍 TODO placeholder replaced with concrete GitHub App details
The old README line 107 contained a TODO comment (<!-- TODO(farrukh): confirm GitHub App install URL + exact permissions/feature list -->) that has now been replaced with a concrete link to https://github.com/apps/garnet-runtime-review and a permissions table at README.md:109-118. The permissions listed (Pull requests: Read & write, Metadata: Read) and the statement that the App does "nothing else — no webhooks, no code access" are worth verifying against the actual GitHub App configuration to ensure accuracy.
Was this helpful? React with 👍 or 👎 to provide feedback.
2 participants
Summary
Resolves the
TODO(farrukh)in README §3 ("Install the companion GitHub App") with concrete copy: install link to https://github.com/apps/garnet-platform (and the Settings → GitHub path in app.garnet.ai), a permission table (Pull requests: Read & write; Metadata: Read), and a note that the App consumes no webhook events.The permission table documents the minimal set the control-plane comment flow actually uses (audited from
githubapp/client.go: installation lookup, installation token, and issue-comment list/create/patch/delete only). If the production app currently requests more, trim it to this set before/with merging this — reducing permissions needs no installer re-approval.Also unblocks the Marketplace listing (ENG-1335): rewrites the
action.yamldescriptionto the 117-char "Runtime review for your PRs — process trees and network destinations from your CI runs, rendered in the pull request." (GitHub's Marketplace limit is 125; the previous description was 141 chars of content). Plus README Outputs-table pipe alignment cosmetics. Docs/metadata only — nosrc//dist/changes; all 77 tests pass.Link to Devin session: https://app.devin.ai/sessions/65415adabada4e1288ab68fd8feecb7a
Requested by: @jadoonf