The GitHub Notifications Browser Extension surfaces your GitHub notifications in a compact popup. It uses GitHub OAuth to authenticate, fetches notifications from the GitHub API, and keeps your access token encrypted in browser storage so that only the extension can read it.
- Background polling with badge counter: A periodic alarm fires every 5 minutes and updates the extension badge with the unread notification count.
- Mark as read (individual & all): Each notification has a "✓ Mark read" button, and a "✓ Mark all as read" button appears when there are notifications.
- Notification grouping by repository: Notifications are grouped under collapsible
<details>elements per repository. - Skeleton loading states: While fetching, three animated skeleton placeholders appear instead of a blank list.
- Keyboard accessibility improvements: The refresh button is focusable and operable with keyboard. All buttons have
aria-labelattributes.
- Chrome: ✅ Supported
- Brave: ✅ Supported
- Firefox:
⚠️ coming soon
- Secure OAuth Login: Uses a Cloudflare Worker to exchange the OAuth code for an access token and AES‑GCM to encrypt it in local storage.
- Real‑Time Notifications: Fetches the latest notifications with the GitHub API and displays them with repository names and context‑specific icons.
- Direct Links: Clicking a notification opens the related issue, pull request, commit, or release on GitHub in a new tab.
- Sign‑Out Support: Easily revoke local credentials and clear stored keys from the extension.
The project consists of two parts:
- Browser Extension (Manifest V3) – background service worker, popup UI, and scripts under
extension/. The background worker runs a periodic alarm (github-notifications-poll) every 5 minutes to poll for new notifications and update the badge count. Notification fetching, mark-as-read, and mark-all-read are all handled via background messages so the popup stays lightweight. - OAuth Service – a Cloudflare Worker located in
service/that exchanges OAuth authorization codes for access tokens, and also proxies mark-read requests (POST /mark-read,POST /mark-all-read) to the GitHub API.
- Clone or download this repository.
- Open
chrome://extensions/orbrave://extensions/. - Enable Developer mode.
- Click Load unpacked and select the
extension/directory.
The extension expects an endpoint that trades an OAuth code for an access token. A ready-made Cloudflare Worker is included:
cd servicenpm installnpm run devto start a local worker ornpm run deployto publish it to Cloudflare.
- Click the extension icon.
- Press Sign in with GitHub to start the OAuth flow.
- After authorization, your notifications appear in the popup as clickable links.
- Use Sign out to clear the encrypted token from local storage.
See docs/privacy.md for details on what data is stored and how it is used.
To customize or extend the project:
- Modify the browser extension sources in
extension/. - Adjust the Cloudflare Worker in
service/if you need different OAuth behavior. - Test your changes locally.
- Commit your changes and push to your GitHub repository.
Contributions are welcome! If you find any issues or want to suggest enhancements, please:
- Fork this repository
- Create a new branch (
git checkout -b feature) - Make changes and commit (
git commit -am 'Add feature') - Push to the branch (
git push origin feature) - Create a pull request
Contribution Guidelines:
- Please ensure that changes follow best practices for accessibility and usability.
- Submit PRs with detailed descriptions of the changes made.
- Ensure all PRs are tested and do not break existing functionality.
Looking forward to your contributions during Hacktoberfest!
- Firefox support (in progress)
- Notification filters (by type / repo)
- Dark mode
This project is licensed under the MIT License. See the LICENSE file for details.
This extension utilizes the GitHub API and browser extension APIs to provide a seamless experience for users.