Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion DEPLOY.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ The login flow requests `scope=repo read:org`:
| `repo` | Read issues, PRs, check runs, workflow runs (includes private repos) |
| `read:org` | `GET /user/orgs` — list user's organizations for the org selector |

**Note:** The `repo` scope grants write access to repositories, but this app never performs write operations (POST/PUT/PATCH/DELETE on repo endpoints). It is read-only by design.
**Note:** The `repo` scope grants write access to repositories. An Octokit request guard blocks all REST write operations (POST/PUT/PATCH/DELETE) and all GraphQL mutations except explicit user-confirmed PR approvals (`addPullRequestReview` with `event: APPROVE`).

### Local development OAuth App

Expand Down
8 changes: 4 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Open issues where you're the creator, assignee, or mentioned. A scope filter let

### Pull Requests

Open PRs with CI status dots (green/yellow/red), review decision badges, size badges (XS–XL by lines changed), and draft indicators. A "blocked" filter catches PRs where checks are failing or a review requested changes. The scope filter works here too. Reviewer avatars stack for multiple reviewers.
Open PRs with CI status dots (green/yellow/red), review decision badges, a read-only `auto` badge when GitHub auto-merge is enabled (with merge method tooltip), size badges (XS–XL by lines changed), draft indicators, and a two-step inline `Approve` button on PR rows requiring approval. A "blocked" filter catches PRs where checks are failing or a review requested changes. The scope filter works here too. Reviewer avatars stack for multiple reviewers.

### Actions

Expand Down Expand Up @@ -128,8 +128,8 @@ src/
layout/ # Header, TabBar, FilterBar
onboarding/ # OnboardingWizard, OrgSelector, RepoSelector
settings/ # SettingsPage, TrackedUsersSection, ThemePicker, Section, SettingRow
shared/ # 19 shared components: FilterInput, FilterChips, StatusDot,
# ReviewBadge, SizeBadge, RoleBadge, SortDropdown, PaginationControls,
shared/ # 28 shared components: FilterInput, FilterChips, StatusDot,
# ReviewBadge, AutoMergeBadge, SizeBadge, RoleBadge, SortDropdown, PaginationControls,
# LoadingSpinner, SkeletonRows, ToastContainer, NotificationDrawer,
# RepoLockControls, UserAvatarBadge, ExpandCollapseButtons,
# RepoGitHubLink, ChevronIcon, ExternalLinkIcon, Tooltip/InfoTooltip
Expand Down Expand Up @@ -170,7 +170,7 @@ pnpm run screenshot # Capture dashboard screenshot

## Security

OAuth tokens are stored in `localStorage` under an app-specific key — this is standard for single-user personal dashboards and matches the threat model here. CSP headers block script injection via Cloudflare (`script-src 'self'` with a SHA-256 exception for the dark-mode initialization script only). An Octokit hook blocks all non-GET requests except `POST /graphql` as a read-only guard — the `repo` scope is required for private repo access, but the app never performs writes. OAuth state is generated with `crypto.getRandomValues` and verified on callback. Token validation runs on every page load via `GET /user`; a 401 clears the stored token immediately.
OAuth tokens are stored in `localStorage` under an app-specific key — this is standard for single-user personal dashboards and matches the threat model here. CSP headers block script injection via Cloudflare (`script-src 'self'` with a SHA-256 exception for the dark-mode initialization script only). An Octokit hook blocks all non-GET REST requests and all GraphQL mutations except the single user-confirmed PR approval mutation (addPullRequestReview with event: APPROVE) — the repo scope is required for private repo access, and all other write operations are rejected client-side. OAuth state is generated with `crypto.getRandomValues` and verified on callback. Token validation runs on every page load via `GET /user`; a 401 clears the stored token immediately.

## Deployment

Expand Down
20 changes: 18 additions & 2 deletions docs/USER_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ If you prefer not to use OAuth, you can sign in with a GitHub Personal Access To
Two token formats are accepted:

- **Classic tokens** (starts with `ghp_`) — recommended. Works across all organizations you belong to. Required scopes: `repo`, `read:org` (under admin:org).
- **Fine-grained tokens** (starts with `github_pat_`) — also work, but only access one organization at a time. Required permissions: Actions (read), Contents (read), Issues (read), Pull requests (read).
- **Fine-grained tokens** (starts with `github_pat_`) — also work, but only access one organization at a time. Required permissions: Actions (read), Contents (read), Issues (read), Pull requests (read and write to approve PRs from the dashboard, or read-only for viewing only).

The token is validated against the GitHub API before being stored. It is saved permanently in your browser's `localStorage` — you will not need to re-enter it on revisit.

Expand Down Expand Up @@ -223,6 +223,18 @@ The dot links to the PR's checks page on GitHub.
| Needs review | Review has been requested but not yet submitted |
| Dismissed | Previously submitted review was dismissed |

#### Auto-Merge Badge

When GitHub auto-merge is enabled on a pull request, a read-only `auto` badge appears next to the review badge (in both comfortable and compact density across the Pull Requests, Dependencies, and Tracked tabs). Hover or focus the badge to view the configured merge method (`merge`, `squash`, or `rebase`).

#### Inline Approve Action

Open, non-draft pull requests not authored by you show an **Approve** button next to the pull request title on hover when branch protection requires a review (`Review needed`) or when a review has been requested of you or your team (unless you have already approved the PR without a fresh re-request).

Approval uses a two-step inline confirmation to prevent accidental clicks:
1. Click **Approve** once to arm confirmation (**Confirm?**, or **Confirm (auto)** when auto-merge is enabled on the PR). The confirmation state resets automatically after 4 seconds, on Escape, or when focus leaves the button.
2. Click **Confirm?** (or **Confirm (auto)**) to submit an `APPROVE` review bound to the PR's current head commit SHA (`commitOID`). If new commits were pushed since the last refresh, GitHub rejects the stale approval and the dashboard triggers a refresh.

#### Size Badges

PR size is computed from total lines changed (additions + deletions):
Expand Down Expand Up @@ -826,7 +838,11 @@ For detailed per-source API call counts, see Settings > API Usage.

OAuth tokens (from "Sign in with GitHub") work across all your organizations and support all features. Classic PATs with the correct scopes (`repo`, `read:org`) behave identically to OAuth.

Fine-grained PATs are limited to one organization at a time. Required permissions: Actions (read), Contents (read), Issues (read), Pull requests (read).
Fine-grained PATs are limited to one organization at a time. Required permissions: Actions (read), Contents (read), Issues (read), Pull requests (read and write to approve PRs from the dashboard, or read-only for viewing only).

**Approving a PR fails with a permission error (403 / FORBIDDEN).**

Your token does not have write permission for pull requests. If you are using a fine-grained Personal Access Token, open GitHub Settings, edit or regenerate the token with **Pull requests** set to **Read and write** (`Pull requests: Read and write`), and replace your token in **Settings > Data > Authentication**.

**Data looks stale after switching back to the tab.**

Expand Down
6 changes: 3 additions & 3 deletions mcp/src/octokit.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { Octokit } from "@octokit/core";
import { throttling } from "@octokit/plugin-throttling";
import { retry } from "@octokit/plugin-retry";
import { paginateRest } from "@octokit/plugin-paginate-rest";
import { isReadOnlyGraphqlQuery } from "../../src/shared/validation.js";

// ── Plugin-extended Octokit class ────────────────────────────────────────────

Expand Down Expand Up @@ -46,12 +47,11 @@ export function createOctokitClient(token: string): GitHubOctokitInstance {
},
});

// Read-only guard: block any non-GET request except POST /graphql
// (GraphQL queries are read-only but always use POST).
// Read-only guard: block any non-GET request except read-only POST /graphql queries.
client.hook.before("request", (options) => {
const method = (options.method ?? "GET").toUpperCase();
if (method === "GET") return;
if (method === "POST" && options.url === "/graphql") return;
if (method === "POST" && options.url === "/graphql" && isReadOnlyGraphqlQuery(options.query)) return;
throw new Error(
`[mcp] Write operation blocked: ${method} ${options.url}. This server is read-only.`
);
Expand Down
37 changes: 37 additions & 0 deletions mcp/tests/octokit.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,43 @@ describe("createOctokitClient — write guard hook", () => {
})
).rejects.toThrow("Write operation blocked");
});

it("blocks GraphQL mutations (including addPullRequestReview) on POST /graphql", async () => {
const { createOctokitClient } = await import("../src/octokit.js");
const client = createOctokitClient("fake-token");

await expect(
client.request("POST /graphql", {
query: `mutation ApprovePullRequest($pullRequestId: ID!, $commitOID: GitObjectID!) {
addPullRequestReview(input: { pullRequestId: $pullRequestId, commitOID: $commitOID, event: APPROVE }) {
pullRequestReview { state }
}
}`,
variables: {
pullRequestId: "PR_kwDOtest42",
commitOID: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
},
})
).rejects.toThrow(/Write operation blocked/);

await expect(
client.request("POST /graphql", {
query: `mutation { mergePullRequest(input: { pullRequestId: "PR_kwDOtest42" }) { clientMutationId } }`,
})
).rejects.toThrow(/Write operation blocked/);

await expect(
client.request("POST /graphql", {
query: `# query { viewer { login } }\nmutation { closePullRequest(input: { pullRequestId: "PR_kwDOtest42" }) { clientMutationId } }`,
})
).rejects.toThrow(/Write operation blocked/);

await expect(
client.request("POST /graphql", {
query: `subscription { viewer { login } }`,
})
).rejects.toThrow(/Write operation blocked/);
});
});

// ── Singleton tests ───────────────────────────────────────────────────────────
Expand Down
Loading
Loading