krz/octosentry

 1# octosentry
 2
 3A macOS menu bar app that aggregates GitHub security alerts — Dependabot,
 4code scanning, and secret scanning — across your repos into a single,
 5severity-ranked feed. No dashboard, no general-purpose GitHub browsing:
 6just a fast triage view that deep-links out to github.com to act.
 7
 8## Features
 9
10- Unified feed across all three GitHub security alert types, normalized
11  onto one severity scale
12- Source badge, repo, GitHub's own severity label, one-line summary, and
13  age for each alert
14- Click an alert to open it directly on github.com
15- Errors and unavailable sources (e.g. an alert type disabled for a repo)
16  are surfaced in the popover instead of failing silently
17- Add or remove watched repos from the popover; a background poll keeps
18  the feed fresh even while it's closed
19- Sign in with GitHub via device authorization — no password or manually
20  generated token needed, and nothing is ever typed into the app itself
21- Zero third-party dependencies — pure SwiftUI and URLSession
22
23## Requirements
24
25- macOS 14 or later
26- A GitHub account with access to whatever repos you want to watch
27
28## Usage
29
301. Build and run the app (see Building, below).
312. Click the shield icon in the menu bar, then **Sign in with GitHub**.
32   You'll get a short code — click **Open GitHub**, enter the code there,
33   and authorize. The popover updates automatically once that completes.
343. Click the gear icon to add or remove watched repos (`owner/repo`).
354. Click any alert to open it on github.com.
36
37If a source shows as unavailable, it usually means that alert type is
38disabled for the repo, or your account lacks permission for it — not
39that something is broken. Classic OAuth's `security_events` scope
40(what device flow grants) may not be sufficient for Dependabot alerts on
41private repos — if you hit that, it needs verifying against a real
42private repo case by case.
43
44## Building
45
46Open `octosentry.xcodeproj` in Xcode and run the `octosentry` scheme.
47The project targets macOS 14 with Swift 6 language mode and strict
48concurrency enabled — no package dependencies to resolve.
49
50## Contributing
51
52Issues and pull requests are welcome. A few things worth knowing before
53you start:
54
55- No third-party dependencies — this is a hard constraint, not a
56  preference.
57- Swift 6 strict concurrency is on; new code should compile clean under
58  it, not suppress it.
59- Match the existing file-per-type layout (models, mapping, API client,
60  views) rather than introducing new architectural patterns.
61
62## License
63
64GPL-3.0 — see [LICENSE](LICENSE).