| 1 | --- |
| 2 | title: Notifications |
| 3 | description: What needs you, and what you follow, as it happens. One thread per issue, pull request, workflow or deployment, with why you were told. Choose what you hear of with subscriptions, watching and email settings. |
| 4 | --- |
| 5 | |
| 6 | **Notifications** tell you when something needs you, or when something |
| 7 | happens to work you answer for or follow: someone asked you to review a |
| 8 | pull request, checks failed on your pull |
| 9 | request, a deployment failed, someone mentioned you. You are never told |
| 10 | about what you did yourself. |
| 11 | |
| 12 | Open them from the bell in the top bar, or from the bottom bar on a |
| 13 | phone. The number on it is what is unread. The bell at the right of the |
| 14 | page's header opens the same notifications in a panel beside the page; its |
| 15 | number is amber while something is waiting on you, red while a failure is |
| 16 | unread, and lavender otherwise. |
| 17 | |
| 18 | ## Threads |
| 19 | |
| 20 | Notifications hold one **thread** for each thing you were told about: |
| 21 | |
| 22 | - an issue |
| 23 | - a pull request |
| 24 | - a workflow on one branch |
| 25 | - a deployment: a project's production, or one pull request's preview |
| 26 | - a workflow run waiting for your review to deploy to an environment |
| 27 | - a repository's security alerts of one kind: its secrets, its code |
| 28 | scanning alerts, or its vulnerable dependencies (see [Security](#security)) |
| 29 | - your security digest for a workspace |
| 30 | |
| 31 | When something new happens on a thread, it comes back to the top of your |
| 32 | notifications, unread, even if you had marked it done. It is not added a second |
| 33 | time. A thread that is snoozed stays snoozed until its time. |
| 34 | |
| 35 | Each card shows the latest activity's title, why you were told (see |
| 36 | [reasons](#reasons)), and, when more than one thing has happened, how many, |
| 37 | such as **3 updates**. g1t keeps the last 10 activities of each thread. |
| 38 | |
| 39 | While a thread is unread it keeps the most urgent of what happened since |
| 40 | you last read it. A failure followed by a comment still shows as a failure |
| 41 | until you read it. |
| 42 | |
| 43 | ## Reasons |
| 44 | |
| 45 | Every thread says why you were told of its latest activity. When you are |
| 46 | told of one thing for more than one reason, the first that applies in this |
| 47 | table is shown. |
| 48 | |
| 49 | | Reason | Shown as | Why you were told | |
| 50 | | --- | --- | --- | |
| 51 | | `review_requested` | review requested | Someone asked you, or a team you are in, to review a pull request; it changes files you own; or you are one of its reviewers. Also a workflow run waiting for you, as one of an [environment's reviewers](/guides/actions/#environments), to approve its deployment, and, for a workspace's owners, a member's token made for the workspace waiting for [approval](/guides/authentication/#a-workspaces-rules-for-tokens) (in Notifications only, never emailed). | |
| 52 | | `assign` | assigned | You were assigned, or you are an assignee. | |
| 53 | | `mention` | mentioned | Someone mentioned you with `@username`, or you were mentioned on it before. | |
| 54 | | `team_mention` | team mentioned | Someone mentioned a [team](/guides/teams/#mentions) you are in with `@workspace/team`, or a team you are in was mentioned on it before. | |
| 55 | | `ci_activity` | CI activity | A check, workflow or deployment on your work finished badly. | |
| 56 | | `security_alert` | security alert | A scan found new secrets, code scanning alerts or vulnerable dependencies on a repository you look after (one thread per repository and kind; see [Security](#security)), a push of yours that push protection refused, a [vulnerability report](/guides/security/advisories/#private-vulnerability-reporting) sent to a repository you look after, a [bypass request](/guides/security/secret-protection/#delegated-bypass) to review or its answer, or your security digest. The workspace's owners and security managers hear of these; watchers who chose **Security alerts** do too, if they can see findings. | |
| 57 | | `state_change` | state changed | It was closed, reopened or merged, or auto-merge you turned on was turned off. | |
| 58 | | `author` | your work | You opened it. Also an owner's answer to your [token made for a workspace](/guides/authentication/#create-a-token) waiting for approval, or its revocation. | |
| 59 | | `comment` | commented | You commented on it. | |
| 60 | | `manual` | subscribed | You subscribed to it yourself. | |
| 61 | | `subscribed` | watching | You watch its repository. | |
| 62 | |
| 63 | ## What lands there |
| 64 | |
| 65 | Each item comes from something that happened on g1t. Who is told depends on |
| 66 | what it was: |
| 67 | |
| 68 | | What happened | Who is told | Reason | Shown as | |
| 69 | | --- | --- | --- | --- | |
| 70 | | Someone asked for reviews on a pull request, or opened one with reviewers | The reviewers asked | `review_requested` | Needs you | |
| 71 | | Someone asked a team to review a pull request | Everyone in the team and its child teams, or, with [review assignment](/guides/teams/#review-assignment), the people picked | `review_requested` | Needs you | |
| 72 | | A workflow run's jobs wait for an [environment's reviewers](/guides/actions/#environments) | Each reviewer, and everyone in a reviewing team ("Deploy is waiting for your review to deploy to production in acme/api"), but not whoever started the run when it may not approve it | `review_requested` | Needs you | |
| 73 | | A pull request changes files a [CODEOWNERS file](/guides/codeowners/) gives you or your team | The owners asked: "acme/api#42 changes files you own" | `review_requested` | Needs you | |
| 74 | | Someone assigned people to an issue or pull request, or opened one with assignees | The people newly assigned | `assign` | Info | |
| 75 | | Checks failed, or could not run, on a pull request | The person the pull request belongs to | `ci_activity` | Error | |
| 76 | | A workflow failed on a pull request | The person the pull request belongs to | `ci_activity` | Error | |
| 77 | | A workflow failed on a branch | Whoever pushed the commit it ran on | `ci_activity` | Error | |
| 78 | | A preview of a pull request failed to deploy | The person the pull request belongs to, and people watching deployments | `ci_activity`, or `subscribed` for watchers | Error | |
| 79 | | Production failed to deploy | Whoever pushed or started it, and people watching deployments | `ci_activity`, or `subscribed` for watchers | Error | |
| 80 | | A deployment went live | People watching deployments. It also [settles](#threads-that-settle-themselves) the failure before it | `subscribed` | Success | |
| 81 | | [Auto-merge](/guides/pull-requests/#auto-merge) was turned off by someone else, or by g1t because the pull request can no longer merge on its own | Whoever turned it on. Not when g1t handed the pull request to the merge queue, which lands it | `state_change` | Needs you | |
| 82 | | A pull request was merged, or an issue or pull request was closed | Its thread's history, for everyone subscribed to it and people watching its kind; the thread [settles](#threads-that-settle-themselves) at once, so it is neither unread nor pushed to you | `state_change`, or `subscribed` for watchers | Success for a merge, else Info | |
| 83 | | An issue was reopened | Everyone subscribed to it, and people watching issues | `state_change`, or `subscribed` for watchers | Info | |
| 84 | | Someone mentioned you with `@username` in a comment | You | `mention` | Info | |
| 85 | | Someone mentioned a team with `@workspace/team` in a comment, or in an issue or pull request they opened | Everyone in the team and its child teams, when the team's notifications are on and the writer can see the team | `team_mention` | Info | |
| 86 | | Someone commented on an issue or pull request | Everyone subscribed to it, and people watching its kind | Why each is subscribed, or `subscribed` for watchers | Info, or Success for an approval | |
| 87 | | An issue or pull request was opened | People watching its kind | `subscribed` | Info | |
| 88 | |
| 89 | "The person a pull request belongs to" is its author. An approval or a |
| 90 | request for changes always reaches that person. A mention in code or in a |
| 91 | quoted line does not count. |
| 92 | |
| 93 | You only see items about repositories you can read. If you lose access to a |
| 94 | repository, its items leave your notifications the next time you open them. |
| 95 | |
| 96 | ## Threads that settle themselves |
| 97 | |
| 98 | A thread that leaves you nothing to do moves to Done by itself, read, the |
| 99 | moment what it told you of is over: a later run passes, the pull request |
| 100 | merges, the review is no longer asked of you. It leaves your unread count, |
| 101 | the bell, [Home](/guides/home/#where-youre-needed)'s **Where you're |
| 102 | needed** and `g1t status`, and |
| 103 | stays under **Done** with its history. New activity brings it back, as with |
| 104 | any thread. |
| 105 | |
| 106 | | A thread about | Settles when | |
| 107 | | --- | --- | |
| 108 | | Anything on an issue or pull request | The pull request is merged or closed, or the issue is closed. A pull request's previews settle with it | |
| 109 | | Your own thread on an issue or pull request | You comment on it or review it | |
| 110 | | A review asked of you | The request to you, or to your team, is removed | |
| 111 | | Checks that failed on your pull request | Its checks pass on its latest commit | |
| 112 | | A workflow that failed on a branch | That workflow passes on that branch | |
| 113 | | A deployment that failed | That project's production, or that preview, deploys | |
| 114 | | A deployment waiting for your review | Its workflow run ends, however it ended | |
| 115 | | A push protection bypass to review | Someone decides it | |
| 116 | | A member's token waiting for your approval | An owner approves, denies or revokes it | |
| 117 | | A workspace invitation | It is accepted, declined or revoked | |
| 118 | | A repository's security alerts | A scan finds none of that kind open | |
| 119 | | g1t stopping on a change it made for you | It picks back up, its head moves, a merge is asked for, or it is merged or closed | |
| 120 | |
| 121 | A thread that settled by itself says why under its title in **Done**, in |
| 122 | a few words, and who did it when someone did: **CI passed in run 330**, |
| 123 | **Merged by @ana**, **Production of site deployed at 8e30fb4**, |
| 124 | **Review no longer asked of you**. A thread you marked done yourself says |
| 125 | nothing there. [Home](/guides/home/#while-you-were-away) lists what |
| 126 | settled for you since your last visit. |
| 127 | |
| 128 | A notification that settled is no longer shown again: tabs you open later |
| 129 | do not replay it, and tabs already open drop it from their recent list. |
| 130 | |
| 131 | What g1t does itself and leaves nothing for you to do is never a |
| 132 | notification: what landed and what deployed is on [Home](/guides/home/). |
| 133 | |
| 134 | ## Subscriptions |
| 135 | |
| 136 | You are **subscribed** to an issue or pull request, and hear of what |
| 137 | happens on it, without doing anything when you: |
| 138 | |
| 139 | - opened it, or asked g1t for it |
| 140 | - are assigned to it |
| 141 | - are one of its reviewers |
| 142 | - commented on it |
| 143 | - were mentioned in it, by name or through a team |
| 144 | |
| 145 | You can also subscribe to any issue or pull request yourself, or |
| 146 | unsubscribe from one. |
| 147 | |
| 148 | | You are | You hear of | |
| 149 | | --- | --- | |
| 150 | | Subscribed | Everything in [What lands there](#what-lands-there) that goes to everyone subscribed: comments, closes, reopens and merges. | |
| 151 | | Unsubscribed | Only what is asked of you or is about your own work: a review request, an assignment, a mention of you or your team, and failed checks, workflows and deployments. Commenting on it, or being mentioned in it, subscribes you again. | |
| 152 | | Ignoring it | Nothing on it at all, not even a mention. Only you can undo this. | |
| 153 | |
| 154 | To subscribe to an issue or pull request, or unsubscribe: |
| 155 | |
| 156 | 1. Open the issue or pull request. |
| 157 | 2. In the sidebar, under **Notifications**, select **Subscribe** or |
| 158 | **Unsubscribe**. |
| 159 | |
| 160 | The line under the button says where you stand, such as "You're subscribed |
| 161 | because you were assigned.", "You're not subscribed. You'll still hear if |
| 162 | you're mentioned or asked to review." or "You ignore this thread." |
| 163 | |
| 164 | To ignore an issue or pull request, use the API: |
| 165 | `PUT /repos/{owner}/{name}/issues/{number}/subscription` with |
| 166 | `"ignored": true`, or the `notifications` tool's `subscribe` action with |
| 167 | `ignored`. See [from the API](#from-the-api). While |
| 168 | you ignore one, its button reads **Stop ignoring**, which puts you back to |
| 169 | the default: subscribed only while you take part. |
| 170 | |
| 171 | ## Watching a repository |
| 172 | |
| 173 | How you **watch** a repository decides what you hear of on it beyond what |
| 174 | you take part in. |
| 175 | |
| 176 | | Level | You hear of | |
| 177 | | --- | --- | |
| 178 | | **Participating and @mentions** | Only what you take part in or are mentioned in. The default. | |
| 179 | | **All activity** | Also every issue and pull request opened, commented on, closed, reopened or merged, and every deployment. | |
| 180 | | **Ignore** | Nothing on the repository at all, not even a mention or a review request. | |
| 181 | | **Custom** | What you take part in, and the kinds you choose: **Issues**, **Pull requests**, **Deployments** and **Security alerts**. Security alerts reach only those with Write on the repository, who can see its findings. | |
| 182 | |
| 183 | To change how you watch a repository: |
| 184 | |
| 185 | 1. Open the repository. |
| 186 | 2. In the header, open the **Watch** menu. |
| 187 | 3. Select a level. For **Custom**, tick the kinds you want. Unticking |
| 188 | every kind puts you back on **Participating and @mentions**. |
| 189 | |
| 190 | A repository you create is watched the way you choose in |
| 191 | [your settings](#settings): **All activity** unless you change it. |
| 192 | |
| 193 | ## Pages that update live |
| 194 | |
| 195 | A repository's pages keep up with it while you are on them, without a |
| 196 | reload and whatever you watch: new commits, pull requests, checks, runs |
| 197 | and comments appear as they happen. |
| 198 | |
| 199 | | Page | Updates when | |
| 200 | | --- | --- | |
| 201 | | **Overview** and **Files** | A branch or tag is pushed, created or deleted, a check or run reports on a commit, a release is published, or a deployment moves. | |
| 202 | | **Commits** | Commits are pushed to the branch. They wait under a **3 new commits · Show** bar at the top instead of moving the list while you read; checks on the commits shown update in place. | |
| 203 | | **Branches** | A branch is pushed, created, renamed or deleted. | |
| 204 | | **Tags** | A tag is pushed or deleted, or a release is published. | |
| 205 | | **Pull requests** and **Issues** | One is opened, updated, reviewed, commented on, checked, merged or closed. | |
| 206 | | A **pull request** | Commits are pushed to it, its checks report, someone reviews or comments, or it is merged or closed. New items join its timeline where you are reading; if you are at the end of the page, it follows them down. | |
| 207 | | An **issue** | Someone comments on it or changes it, or a pull request linked to it moves. | |
| 208 | | **Actions** and a **run** | A run starts, one of its jobs starts or finishes, or the run finishes. A running job's log streams on its own. | |
| 209 | | **Security** | An alert is opened, fixed, dismissed or reopened. | |
| 210 | | Your workspace's **Home** | Something lands, runs, deploys or comes to need you in its projects (the first 25). See [Home](/guides/home/#while-the-page-is-open). | |
| 211 | |
| 212 | A page refreshes a second after the last change it shows, so a burst of |
| 213 | them is one refresh. It never refreshes while you are typing in it or have |
| 214 | a dialog open: the change waits until you leave the field or close the |
| 215 | dialog. A tab you are not looking at refreshes at most once a minute, and |
| 216 | as soon as you come back to it. |
| 217 | |
| 218 | How it works: each signed-in tab keeps one live connection to g1t (the |
| 219 | same one that brings notifications and chat counts). Opening a |
| 220 | repository's page asks to follow that repository, and g1t first checks you |
| 221 | can read it. From then on, every push, pull request, issue, comment, |
| 222 | review, check, run, release and security alert there sends that tab a |
| 223 | short note naming only what kind of thing changed and where: a branch, a |
| 224 | number, a commit. Never a title, a message or code. The page then reads |
| 225 | itself again, with your access as it is now. Following lasts fifteen |
| 226 | minutes and is renewed while the page stays open, so someone who loses |
| 227 | access stops hearing of the repository within that time. |
| 228 | |
| 229 | Signed out, on a public repository, or while the live connection is down, |
| 230 | pages fall back to checking for themselves: when you come back to the tab |
| 231 | (at most every 30 seconds), and once a minute while it is in view. |
| 232 | |
| 233 | ## Security |
| 234 | |
| 235 | Security alerts are told the way they can be lived with. A scan that finds |
| 236 | forty vulnerabilities is one notification, not forty: each repository has |
| 237 | one thread per kind of alert (secrets, code scanning alerts, vulnerable |
| 238 | dependencies), titled by what the latest scan found, "3 new vulnerabilities |
| 239 | in acme/rocket: 1 critical, 2 high", with the worst new alert as its line. |
| 240 | The next scan brings the same thread back up to date rather than adding |
| 241 | another; a scan that only fixed or dismissed alerts refreshes it quietly, |
| 242 | "2 open vulnerabilities in acme/rocket: 2 high" with "1 fixed" in its |
| 243 | history, without waking you, and marks it done when nothing is left open. |
| 244 | |
| 245 | What reaches you, and when, follows the alert's severity: |
| 246 | |
| 247 | | Alert | Who | When | |
| 248 | | --- | --- | --- | |
| 249 | | Critical or high | The workspace's owners and security managers, and watchers who chose **Security alerts**. | At once, as an error, with a pop-up like a mention's. | |
| 250 | | A push of yours that push protection refused | You. | At once, whatever you chose. | |
| 251 | | A vulnerability report, a bypass request | The owners and security managers; the reviewers. | At once, as something waiting on you. | |
| 252 | | Medium or low | The same people. | In your **security digest**, once a day or once a week as you choose, or at once, or never. | |
| 253 | | A published advisory | Watchers who chose **Security alerts**. | At once, as information. | |
| 254 | |
| 255 | The **security digest** is one notification and one email per workspace, |
| 256 | "Security digest for acme: 4 new medium vulnerabilities in 2 repositories, |
| 257 | 1 new low secret in 1 repository", naming the newest alerts, sent in the |
| 258 | morning (UTC): every day, or on Mondays. Owners and security managers get |
| 259 | the urgent alerts whatever their settings say; those alerts are theirs to |
| 260 | act on. Everyone else can turn the urgent ones off too, and anyone can |
| 261 | choose how the rest arrive, in [Settings](#settings). |
| 262 | |
| 263 | Fixes and dismissals never make a notification of their own. The findings |
| 264 | themselves are always on each repository's [Security page](/guides/security/). |
| 265 | |
| 266 | ## Email |
| 267 | |
| 268 | You can also be emailed when you are told of something. By default, g1t |
| 269 | emails you for three reasons: **review requested**, **mentioned** and |
| 270 | **security alert**. Each time you are told of something |
| 271 | for a reason you chose, g1t sends one email with what happened and a link |
| 272 | to it; a security digest is one email. |
| 273 | |
| 274 | An email is sent only when: |
| 275 | |
| 276 | - your account's email address is confirmed, and |
| 277 | - you can still read the repository it is about. |
| 278 | |
| 279 | The foot of each email says why you got it, and links to |
| 280 | [g1t.sh/settings/notifications](https://g1t.sh/settings/notifications). |
| 281 | |
| 282 | ## On your phone |
| 283 | |
| 284 | [The phone app](/guides/mobile/) gets the same notifications as |
| 285 | [browser notifications](/guides/chat/#notifications), under the same |
| 286 | rules: |
| 287 | |
| 288 | - only what you chose under **Notify me about**, for each workspace; |
| 289 | - never while **Do not disturb** is on; |
| 290 | - nothing from a conversation you [muted](/guides/chat/#star-and-mute), |
| 291 | but a direct message or a mention of you; |
| 292 | - nothing while a g1t tab, or the app itself, is in front of you: it tells you there. |
| 293 | |
| 294 | Your phone is registered when you allow notifications in the app. |
| 295 | **Send a test notification**, here or in the app under **More**, reaches it too. Signing out of the app stops |
| 296 | them on that phone. g1t pushes to your 10 most recent phones, and stops |
| 297 | on its own for a phone the app was removed from. Phones are reached |
| 298 | through Expo's push service, which hands each notification to Google |
| 299 | (Android) or Apple (iOS); a [self-hosted g1t](/guides/self-hosting/#the-phone-app) |
| 300 | can turn that off. |
| 301 | |
| 302 | ## Settings |
| 303 | |
| 304 | **Settings → Notifications**, at |
| 305 | [g1t.sh/settings/notifications](https://g1t.sh/settings/notifications), |
| 306 | holds your choices: |
| 307 | |
| 308 | | Setting | What it does | Default | |
| 309 | | --- | --- | --- | |
| 310 | | **Sounds**, **Sound set**, **Volume**, one switch per sound | What chat sounds like; see [Sounds and do not disturb](/guides/chat/#sounds-and-do-not-disturb). | On, Soft, 60, all but Sent | |
| 311 | | **Do not disturb** | Silences sounds, pop-ups, and browser and phone notifications until a time you choose. | Off | |
| 312 | | **Desktop notifications** | A system notification from an open tab for a message to you while the window is behind another. In [the desktop app](/guides/desktop/) it is on, and the app shows them itself. | Off | |
| 313 | | **Notify me about**, **Browser notifications** | What pops up and is pushed; see [chat notifications](/guides/chat/#notifications). | DMs and mentions; off | |
| 314 | | **Email** | One checkbox per reason: you are also emailed when you are told of something for it. | review requested, mentioned, security alert | |
| 315 | | **Security: Critical and high alerts at once** | Whether urgent alerts on repositories you watch for security reach you at once. The workspaces you own or manage security for tell you whatever this says. | On | |
| 316 | | **Security: Medium and low alerts** | In a daily digest, in a weekly digest, at once, or not at all. | Daily digest | |
| 317 | | **Repositories you create** | How you watch a new repository you create: **Participating and @mentions** or **All activity**. | All activity | |
| 318 | | **Watched repositories** | Every repository you watch other than the default way, with how. | | |
| 319 | |
| 320 | ## Tabs |
| 321 | |
| 322 | | Tab | Shows | |
| 323 | | --- | --- | |
| 324 | | **All** | Everything, with what is waiting on you first | |
| 325 | | **Needs you** | What is waiting on you, such as a review asked of you | |
| 326 | | **Errors** | Failed checks, workflows and deployments | |
| 327 | | **Success** | Merges, approvals, and deployments that went live | |
| 328 | | **Info** | Mentions, comments, assignments, and what you watch | |
| 329 | |
| 330 | The count beside each tab is what is unread under it. |
| 331 | |
| 332 | ## The Notifications page |
| 333 | |
| 334 | The bell in the top bar opens |
| 335 | [g1t.sh/notifications](https://g1t.sh/notifications): every thread, a page |
| 336 | at a time, under the same tabs. Its sidebar chooses what you look at: |
| 337 | |
| 338 | | In the sidebar | Shows | |
| 339 | | --- | --- | |
| 340 | | **Everything** | Threads you have not marked done, with how many are unread | |
| 341 | | **Saved** | Threads you saved, done or not | |
| 342 | | **Done** | Threads you marked done. Select ↶ on one to move it back | |
| 343 | | **Why you were told** | Only threads told for one [reason](#reasons), or **Any reason** | |
| 344 | |
| 345 | The reason is kept in the address as `?reason=`, such as |
| 346 | [g1t.sh/notifications?reason=review_requested](https://g1t.sh/notifications?reason=review_requested), |
| 347 | so you can bookmark it. On a phone, and on a narrow window, where the |
| 348 | sidebar is a drawer, the page shows the views as tabs and the reason as a |
| 349 | menu above the list. |
| 350 | |
| 351 | ## Work through it |
| 352 | |
| 353 | 1. Open the Notifications page, or select the bell in the page's header to |
| 354 | work through them in a panel beside the page. |
| 355 | 2. Select an item to open what it is about. It is marked read, and the |
| 356 | panel closes. |
| 357 | 3. Point at an item (on a phone, the buttons are always there) to act on it |
| 358 | without opening it: |
| 359 | |
| 360 | | Action | What it does | |
| 361 | | --- | --- | |
| 362 | | **Done** (✓) | Moves the thread out of Everything and into Done, until something new happens on it | |
| 363 | | **Mark as read** / **Mark as unread** | Changes whether it counts as unread | |
| 364 | | **Save** | Keeps it under Saved, even after it is done | |
| 365 | | **Snooze until** | Hides it for 3 hours, until tomorrow, or for a week, then brings it back | |
| 366 | |
| 367 | **Mark all read** marks everything under the tab you are on as read. |
| 368 | **Open Notifications**, at the foot of the panel, goes to the page. |
| 369 | |
| 370 | [Home](/guides/home/) shows the unread warnings and failures waiting on you, |
| 371 | with what else needs you across the workspace. |
| 372 | |
| 373 | ## From the API |
| 374 | |
| 375 | Everything here is also in the REST API and the MCP server, for a personal |
| 376 | access token or an OAuth sign-in, so a coding agent you connect can work |
| 377 | through your notifications as you. A workspace's token cannot use it. |
| 378 | Reading needs the `notifications:read` scope, and changing anything |
| 379 | `notifications:write`; the Agent [preset](/guides/authentication/#presets) |
| 380 | has both. |
| 381 | |
| 382 | | Route | MCP action | What it does | |
| 383 | | --- | --- | --- | |
| 384 | | [`GET /notifications`](/reference/api/notifications/list-notifications/) | `list` | Your unread threads, latest first. Filter by `reason`, `severity`, `participating`, `since` and `before`; `all` adds read ones; `view` lists `saved` or `done`. | |
| 385 | | [`PUT /notifications`](/reference/api/notifications/mark-notifications-read/) | `mark_all_read` | Mark everything read up to `last_read_at`. | |
| 386 | | [`GET /notifications/threads/{id}`](/reference/api/notifications/get-notification-thread/) | `get` | One thread, its last 10 activities, and your subscription. | |
| 387 | | [`PATCH /notifications/threads/{id}`](/reference/api/notifications/mark-thread-read/) | `mark_read` | Mark a thread read, or unread. | |
| 388 | | [`DELETE /notifications/threads/{id}`](/reference/api/notifications/mark-thread-done/) | `done` | Mark a thread done. | |
| 389 | | [`PUT /notifications/threads/{id}/saved`](/reference/api/notifications/save-thread/) | `save` | Save a thread; `DELETE` unsaves it. | |
| 390 | | [`PUT /notifications/threads/{id}/snooze`](/reference/api/notifications/snooze-thread/) | `snooze` | Snooze a thread until `until`; `DELETE` brings it back. | |
| 391 | | [`PUT /repos/{owner}/{name}/issues/{number}/subscription`](/reference/api/notifications/set-issue-subscription/) | `subscribe` | Subscribe to an issue or pull request, unsubscribe, or ignore it. `GET` reads it and `DELETE` unsubscribes. The same works at `/notifications/threads/{id}/subscription`. | |
| 392 | | [`PUT /repos/{owner}/{name}/subscription`](/reference/api/notifications/set-repo-subscription/) | `watch` | Watch a repository at a `level`. `GET` reads it and `DELETE` goes back to the default. | |
| 393 | | [`GET /user/subscriptions`](/reference/api/notifications/list-watched-repos/) | `watched` | The repositories you watch other than the default way. | |
| 394 | |
| 395 | `GET /repos/{owner}/{name}/notifications` and |
| 396 | `PUT /repos/{owner}/{name}/notifications` list and mark one repository's |
| 397 | threads. Every action of the `notifications` tool is in |
| 398 | [MCP tools](/reference/mcp/#notifications). |
| 399 | |
| 400 | For example, to list the reviews waiting on you: |
| 401 | |
| 402 | ```sh |
| 403 | curl "https://api.g1t.sh/notifications?reason=review_requested" \ |
| 404 | -H "Authorization: Bearer $G1T_TOKEN" |
| 405 | ``` |
| 406 | |
| 407 | ## How long items are kept |
| 408 | |
| 409 | Threads you mark done are removed 30 days after you mark them. Any other |
| 410 | thread is removed once nothing has happened on it for 180 days. Saved |
| 411 | threads are kept until you unsave them. |