### Why / What / How
**Why:** We have GitHub trigger and repo/issue/PR blocks, but no way for
agents to work with the user's GitHub notification inbox — e.g.
inbox-zero automations, notification triage, or surfacing review
requests. GitHub's Notifications API is poll-only (no webhook events
exist for it), so inbox automations run as scheduled graphs using
regular blocks.
**What:** Adds six blocks covering the [GitHub Notifications REST
API](https://docs.github.com/en/rest/activity/notifications): listing
notifications and getting / marking read / marking done / unsubscribing
from notification threads, plus mark-all-as-read. Also adds a
`GithubGetUserInfoBlock` and extends `GithubListPRReviewersBlock` with
review status info, enabling agents to determine whether the account's
user is (still) involved in a PR (example use case: auto-archiving stale
review-request notifications).
**How:** New `notifications.py` in the GitHub blocks package, following
the existing block conventions there. Notification endpoints live under
`/notifications` rather than `/repos/...`, so the blocks use
`get_api(credentials, convert_urls=False)` with absolute URLs. API
responses are normalized into a shared `NotificationItem` shape whose
`thread_id` chains into the per-thread blocks and whose `subject_url` is
converted best-effort from the API URL to the corresponding github.com
page URL. Notification blocks use the minimal `notifications` OAuth
scope.
### Changes 🏗️
- Add `GithubListNotificationsBlock`: lists the inbox with include-read
/ participating-only / `since` / `before` filters and optional repo
scoping; yields the full list plus each notification individually
- Add `GithubGetNotificationThreadBlock`: fetches one thread and exposes
title, reason, unread, subject type/URL, and repository as separate
outputs
- Add `GithubMarkNotificationsAsReadBlock`: marks all notifications as
read, optionally repo-scoped, with optional `last_read_at` cutoff
- Add `GithubMarkNotificationThreadAsReadBlock` and
`GithubMarkNotificationThreadAsDoneBlock`: per-thread read / done
- Add `GithubUnsubscribeNotificationThreadBlock`: mutes a thread
- Add `GithubGetUserInfoBlock`: fetches info on a given user, or the
authenticated user if no username is given
- Extend `GithubListPRReviewersBlock`: new `include_past_reviewers`
toggle (default off) to also list users who already submitted a review,
plus `review_requested` / `has_reviewed` / `review_state` fields on each
reviewer item; the extra API call is gated behind the toggle so existing
graphs are unaffected
- Refactor: hoist `GITHUB_API_URL` constant into `_api.py` and reuse it
### Checklist 📋
#### For code changes:
- [x] I have clearly listed my changes in the PR description
- [x] I have made a test plan
- [x] I have tested my changes according to the test plan:
- [x] `poetry run pytest backend/blocks/test/test_block.py` — full block
suite passes, including schema validation + mocked execution of all
new/changed blocks
- [x] `poetry run pytest backend/blocks/github/test_github_blocks.py` —
passes
- [ ] Live-run the List / Mark as read blocks against a real GitHub
account (not done — mocked execution only)
<details>
<summary>Example test plan</summary>
- [ ] Create from scratch and execute an agent with at least 3 blocks
- [ ] Import an agent from file upload, and confirm it executes
correctly
- [ ] Upload agent to marketplace
- [ ] Import an agent from marketplace and confirm it executes correctly
- [ ] Edit an agent from monitor, and confirm it executes correctly
</details>
#### For configuration changes:
- [x] `.env.default` is updated or already compatible with my changes
- [x] `docker-compose.yml` is updated or already compatible with my
changes
- [x] I have included a list of my configuration changes in the PR
description (under **Changes**)
<details>
<summary>Examples of configuration changes</summary>
- Changing ports
- Adding new services that need to communicate with each other
- Secrets or environment variable changes
- New or infrastructure changes such as databases
</details>
---------
Co-authored-by: Claude Fable 5 <[email protected]>
<!-- Clearly explain the need for these changes: -->
we met some reality when merging into the docs site but this fixes it
### Changes 🏗️
updates paths, adds some guides
<!-- Concisely describe all of the changes made in this pull request:
-->
update to match reality
### Checklist 📋
#### For code changes:
- [x] I have clearly listed my changes in the PR description
- [x] I have made a test plan
- [x] I have tested my changes according to the test plan:
<!-- Put your test plan here: -->
- [x] deploy it and validate
<!-- CURSOR_SUMMARY -->
---
> [!NOTE]
> Aligns block integrations documentation with GitBook.
>
> - Changes generator default output to
`docs/integrations/block-integrations` and writes overview `README.md`
and `SUMMARY.md` at `docs/integrations/`
> - Adds GitBook frontmatter and hint syntax to overview; prefixes block
links with `block-integrations/`
> - Introduces `generate_summary_md` to build GitBook navigation
(including optional `guides/`)
> - Preserves per-block manual sections and adds optional `extras` +
file-level `additional_content`
> - Updates sync checker to validate parent `README.md` and `SUMMARY.md`
> - Rewrites `docs/integrations/README.md` with GitBook frontmatter and
updated links; adds `docs/integrations/SUMMARY.md`
> - Adds new guides: `guides/llm-providers.md`,
`guides/voice-providers.md`
>
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
fdb7ff8111. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->
---------
Co-authored-by: Claude Opus 4.5 <[email protected]>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: bobby.gaffin <[email protected]>
