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- Zero third-party dependencies — pure SwiftUI and URLSession
18
19## Requirements
20
21- macOS 14 or later
22- A GitHub personal access token (fine-grained or classic) with read
23  access to Dependabot alerts, code scanning alerts, and secret scanning
24  alerts for the repo you want to watch
25
26## Usage
27
28octosentry currently watches a single, hardcoded repo and reads its
29GitHub token from the `GITHUB_TOKEN` environment variable — this is a
30development-only shortcut ahead of a proper device authorization flow.
31
321. Build and run the app (see Building, below).
332. Set `GITHUB_TOKEN` in your **personal, non-shared** Xcode scheme
34   (Product → Scheme → Edit Scheme… → Run → Arguments →
35   Environment Variables). Don't add it to a shared scheme — that would
36   commit the token to git.
373. Click the shield icon in the menu bar to open the popover. It fetches
38   automatically on open, or use the refresh button.
394. Click any alert to open it on github.com.
40
41If a source shows as unavailable, it usually means that alert type is
42disabled for the repo, or the token is missing that one permission — not
43that something is broken.
44
45## Building
46
47Open `octosentry.xcodeproj` in Xcode and run the `octosentry` scheme.
48The project targets macOS 14 with Swift 6 language mode and strict
49concurrency enabled — no package dependencies to resolve.
50
51## Contributing
52
53Issues and pull requests are welcome. A few things worth knowing before
54you start:
55
56- No third-party dependencies — this is a hard constraint, not a
57  preference.
58- Swift 6 strict concurrency is on; new code should compile clean under
59  it, not suppress it.
60- Match the existing file-per-type layout (models, mapping, API client,
61  views) rather than introducing new architectural patterns.
62
63## License
64
65GPL-3.0 — see [LICENSE](LICENSE).