| 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: an agent is waiting on you, |
| 8 | someone asked you to review a 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 | |
| 28 | When something new happens on a thread, it comes back to the top of your |
| 29 | notifications, unread, even if you had marked it done. It is not added a second |
| 30 | time. A thread that is snoozed stays snoozed until its time. |
| 31 | |
| 32 | Each card shows the latest activity's title, why you were told (see |
| 33 | [reasons](#reasons)), and, when more than one thing has happened, how many, |
| 34 | such as **3 updates**. g1t keeps the last 10 activities of each thread. |
| 35 | |
| 36 | While a thread is unread it keeps the most urgent of what happened since |
| 37 | you last read it. A failure followed by a comment still shows as a failure |
| 38 | until you read it. |
| 39 | |
| 40 | ## Reasons |
| 41 | |
| 42 | Every thread says why you were told of its latest activity. When you are |
| 43 | told of one thing for more than one reason, the first that applies in this |
| 44 | table is shown. |
| 45 | |
| 46 | | Reason | Shown as | Why you were told | |
| 47 | | --- | --- | --- | |
| 48 | | `agent` | agent waiting | An agent is waiting on you: it asked a question, or it stopped until a person steps in. | |
| 49 | | `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). | |
| 50 | | `assign` | assigned | You were assigned, or you are an assignee. | |
| 51 | | `mention` | mentioned | Someone mentioned you with `@username`, or you were mentioned on it before. | |
| 52 | | `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. | |
| 53 | | `ci_activity` | CI activity | A check, workflow or deployment on your work finished badly, or recovered. | |
| 54 | | `security_alert` | security alert | A new secret, code scanning or vulnerability alert on a repository you look after, a push of yours that push protection blocked, or a [bypass request](/guides/security/secret-protection/#delegated-bypass) to review or its answer. The workspace's owners hear of new alerts; watchers who chose **Security alerts** do too, if they can see findings. | |
| 55 | | `state_change` | state changed | It was closed, reopened or merged. | |
| 56 | | `author` | your work | You opened it, or you asked g1t for it. Also an owner's answer to your [token made for a workspace](/guides/authentication/#create-a-token) waiting for approval, or its revocation. | |
| 57 | | `comment` | commented | You commented on it. | |
| 58 | | `manual` | subscribed | You subscribed to it yourself. | |
| 59 | | `subscribed` | watching | You watch its repository. | |
| 60 | |
| 61 | ## What lands there |
| 62 | |
| 63 | Each item comes from something that happened on g1t. Who is told depends on |
| 64 | what it was: |
| 65 | |
| 66 | | What happened | Who is told | Reason | Shown as | |
| 67 | | --- | --- | --- | --- | |
| 68 | | An agent asked a question of the agent on a pull request, or handed it work | The person the pull request belongs to, and its issue's author and assignees | `agent` | Needs you | |
| 69 | | g1t stopped on a pull request until a person steps in | The same people | `agent` | Needs you | |
| 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; after a failure, also whoever was told of the failure | `ci_activity`, or `subscribed` for watchers | Success | |
| 81 | | g1t finished a change and marked it ready for review | The person who asked g1t for it | `author` | Success | |
| 82 | | g1t reviewed a pull request | The person the pull request belongs to | `author` | Success when approved, Info when it asks for changes | |
| 83 | | A pull request was merged | Everyone subscribed to it, and people watching pull requests | `state_change`, or `subscribed` for watchers | Success | |
| 84 | | An issue or pull request was closed, or an issue was reopened | Everyone subscribed to it, and people watching its kind | `state_change`, or `subscribed` for watchers | Info | |
| 85 | | Someone mentioned you with `@username` in a comment | You | `mention` | Info | |
| 86 | | 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 | |
| 87 | | 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 | |
| 88 | | One of your workspace's agents commented on or reviewed an issue or pull request, as itself | The same people, and the person the pull request belongs to for a review; shown as from "Margo (agent)", with "(advisory)" on a review. See [agent reviews](/guides/pull-requests/#agent-reviews) | Why each is subscribed, or `author` for a review | Info, or Success for an approval | |
| 89 | | An issue or pull request was opened | People watching its kind | `subscribed` | Info | |
| 90 | |
| 91 | "The person a pull request belongs to" is its author, or, for a change g1t |
| 92 | made, the person who asked for it. An approval or a request for changes |
| 93 | always reaches that person. g1t itself is never told. A mention in code or |
| 94 | in a quoted line does not count. |
| 95 | |
| 96 | Some threads close themselves once they no longer need you: |
| 97 | |
| 98 | - When an agent was waiting on you, the thread moves to Done as soon as the |
| 99 | agent picks back up: it resumes, its pull request changes, a merge is |
| 100 | asked for, or the pull request is merged or closed. |
| 101 | - When a review request to you is removed, that thread moves to Done. |
| 102 | |
| 103 | New activity brings either back, as with any thread. |
| 104 | |
| 105 | You only see items about repositories you can read. If you lose access to a |
| 106 | repository, its items leave your notifications the next time you open them. |
| 107 | |
| 108 | ## Subscriptions |
| 109 | |
| 110 | You are **subscribed** to an issue or pull request, and hear of what |
| 111 | happens on it, without doing anything when you: |
| 112 | |
| 113 | - opened it, or asked g1t for it |
| 114 | - are assigned to it |
| 115 | - are one of its reviewers |
| 116 | - commented on it |
| 117 | - were mentioned in it, by name or through a team |
| 118 | |
| 119 | You can also subscribe to any issue or pull request yourself, or |
| 120 | unsubscribe from one. |
| 121 | |
| 122 | | You are | You hear of | |
| 123 | | --- | --- | |
| 124 | | Subscribed | Everything in [What lands there](#what-lands-there) that goes to everyone subscribed: comments, closes, reopens and merges. | |
| 125 | | Unsubscribed | Only what is asked of you or is about your own work: an agent waiting on you, 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. | |
| 126 | | Ignoring it | Nothing on it at all, not even a mention. Only you can undo this. | |
| 127 | |
| 128 | To subscribe to an issue or pull request, or unsubscribe: |
| 129 | |
| 130 | 1. Open the issue or pull request. |
| 131 | 2. In the sidebar, under **Notifications**, select **Subscribe** or |
| 132 | **Unsubscribe**. |
| 133 | |
| 134 | The line under the button says where you stand, such as "You're subscribed |
| 135 | because you were assigned.", "You're not subscribed. You'll still hear if |
| 136 | you're mentioned or asked to review." or "You ignore this thread." |
| 137 | |
| 138 | To ignore an issue or pull request, use the API: |
| 139 | `PUT /repos/{owner}/{name}/issues/{number}/subscription` with |
| 140 | `"ignored": true`, or the `notifications` tool's `subscribe` action with |
| 141 | `ignored`. See [from the API and agents](#from-the-api-and-agents). While |
| 142 | you ignore one, its button reads **Stop ignoring**, which puts you back to |
| 143 | the default: subscribed only while you take part. |
| 144 | |
| 145 | ## Watching a repository |
| 146 | |
| 147 | How you **watch** a repository decides what you hear of on it beyond what |
| 148 | you take part in. |
| 149 | |
| 150 | | Level | You hear of | |
| 151 | | --- | --- | |
| 152 | | **Participating and @mentions** | Only what you take part in or are mentioned in. The default. | |
| 153 | | **All activity** | Also every issue and pull request opened, commented on, closed, reopened or merged, and every deployment. | |
| 154 | | **Ignore** | Nothing on the repository at all, not even a mention or a review request. | |
| 155 | | **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. | |
| 156 | |
| 157 | To change how you watch a repository: |
| 158 | |
| 159 | 1. Open the repository. |
| 160 | 2. In the header, open the **Watch** menu. |
| 161 | 3. Select a level. For **Custom**, tick the kinds you want. Unticking |
| 162 | every kind puts you back on **Participating and @mentions**. |
| 163 | |
| 164 | A repository you create is watched the way you choose in |
| 165 | [your settings](#settings): **All activity** unless you change it. |
| 166 | |
| 167 | ## Email |
| 168 | |
| 169 | You can also be emailed when you are told of something. By default, g1t |
| 170 | emails you for three reasons: **agent waiting**, **review requested** and |
| 171 | **mentioned**. Each time you are told of something for a reason you chose, |
| 172 | g1t sends one email with what happened and a link to it. |
| 173 | |
| 174 | An email is sent only when: |
| 175 | |
| 176 | - your account's email address is confirmed, and |
| 177 | - you can still read the repository it is about. |
| 178 | |
| 179 | The foot of each email says why you got it, and links to |
| 180 | [g1t.sh/settings/notifications](https://g1t.sh/settings/notifications). |
| 181 | |
| 182 | ## On your phone |
| 183 | |
| 184 | [The phone app](/guides/mobile/) gets the same notifications as |
| 185 | [browser notifications](/guides/chat/#notifications), under the same |
| 186 | rules: |
| 187 | |
| 188 | - only what you chose under **Notify me about**, for each workspace; |
| 189 | - never while **Do not disturb** is on; |
| 190 | - nothing from a conversation you [muted](/guides/chat/#star-and-mute), |
| 191 | but a direct message or a mention of you; |
| 192 | - nothing while a g1t tab, or the app itself, is in front of you: it tells you there. |
| 193 | |
| 194 | Your phone is registered when you allow notifications in the app. |
| 195 | **Send a test notification**, here or in the app under **More**, reaches it too. Signing out of the app stops |
| 196 | them on that phone. g1t pushes to your 10 most recent phones, and stops |
| 197 | on its own for a phone the app was removed from. Phones are reached |
| 198 | through Expo's push service, which hands each notification to Google |
| 199 | (Android) or Apple (iOS); a [self-hosted g1t](/guides/self-hosting/#the-phone-app) |
| 200 | can turn that off. |
| 201 | |
| 202 | ## Settings |
| 203 | |
| 204 | **Settings → Notifications**, at |
| 205 | [g1t.sh/settings/notifications](https://g1t.sh/settings/notifications), |
| 206 | holds your choices: |
| 207 | |
| 208 | | Setting | What it does | Default | |
| 209 | | --- | --- | --- | |
| 210 | | **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 | |
| 211 | | **Do not disturb** | Silences sounds, pop-ups, and browser and phone notifications until a time you choose. | Off | |
| 212 | | **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 | |
| 213 | | **Notify me about**, **Browser notifications** | What pops up and is pushed; see [chat notifications](/guides/chat/#notifications). | DMs and mentions; off | |
| 214 | | **Email** | One checkbox per reason: you are also emailed when you are told of something for it. | agent waiting, review requested, mentioned | |
| 215 | | **Repositories you create** | How you watch a new repository you create: **Participating and @mentions** or **All activity**. | All activity | |
| 216 | | **Watched repositories** | Every repository you watch other than the default way, with how. | | |
| 217 | |
| 218 | ## Tabs |
| 219 | |
| 220 | | Tab | Shows | |
| 221 | | --- | --- | |
| 222 | | **All** | Everything, with what is waiting on you first | |
| 223 | | **Needs you** | What is waiting on you: an agent, or a review asked of you | |
| 224 | | **Errors** | Failed checks, workflows and deployments | |
| 225 | | **Success** | Merges, approvals, finished agent work, and deployments that went live | |
| 226 | | **Info** | Mentions, comments, assignments, and what you watch | |
| 227 | |
| 228 | The count beside each tab is what is unread under it. |
| 229 | |
| 230 | ## The Notifications page |
| 231 | |
| 232 | The bell in the top bar opens |
| 233 | [g1t.sh/notifications](https://g1t.sh/notifications): every thread, a page |
| 234 | at a time, under the same tabs. Its sidebar chooses what you look at: |
| 235 | |
| 236 | | In the sidebar | Shows | |
| 237 | | --- | --- | |
| 238 | | **Everything** | Threads you have not marked done, with how many are unread | |
| 239 | | **Saved** | Threads you saved, done or not | |
| 240 | | **Done** | Threads you marked done. Select ↶ on one to move it back | |
| 241 | | **Why you were told** | Only threads told for one [reason](#reasons), or **Any reason** | |
| 242 | |
| 243 | The reason is kept in the address as `?reason=`, such as |
| 244 | [g1t.sh/notifications?reason=review_requested](https://g1t.sh/notifications?reason=review_requested), |
| 245 | so you can bookmark it. On a phone, and on a narrow window, where the |
| 246 | sidebar is a drawer, the page shows the views as tabs and the reason as a |
| 247 | menu above the list. |
| 248 | |
| 249 | ## Work through it |
| 250 | |
| 251 | 1. Open the Notifications page, or select the bell in the page's header to |
| 252 | work through them in a panel beside the page. |
| 253 | 2. Select an item to open what it is about. It is marked read, and the |
| 254 | panel closes. |
| 255 | 3. Point at an item (on a phone, the buttons are always there) to act on it |
| 256 | without opening it: |
| 257 | |
| 258 | | Action | What it does | |
| 259 | | --- | --- | |
| 260 | | **Done** (✓) | Moves the thread out of Everything and into Done, until something new happens on it | |
| 261 | | **Mark as read** / **Mark as unread** | Changes whether it counts as unread | |
| 262 | | **Save** | Keeps it under Saved, even after it is done | |
| 263 | | **Snooze until** | Hides it for 3 hours, until tomorrow, or for a week, then brings it back | |
| 264 | |
| 265 | **Mark all read** marks everything under the tab you are on as read. |
| 266 | **Open Notifications**, at the foot of the panel, goes to the page. |
| 267 | |
| 268 | [Home](/guides/home/) shows the unread warnings and failures waiting on you, |
| 269 | with what else needs you across the workspace. |
| 270 | |
| 271 | ## From the API and agents |
| 272 | |
| 273 | Everything here is also in the REST API and the MCP server, for a personal |
| 274 | access token or an OAuth sign-in. A workspace's token cannot use it, and |
| 275 | neither can g1t's own agents: they act as `g1t`, which has no notifications. |
| 276 | Reading needs the `notifications:read` scope, and changing anything |
| 277 | `notifications:write`; the Agent [preset](/guides/authentication/#presets) |
| 278 | has both. |
| 279 | |
| 280 | | Route | MCP action | What it does | |
| 281 | | --- | --- | --- | |
| 282 | | [`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`. | |
| 283 | | [`PUT /notifications`](/reference/api/notifications/mark-notifications-read/) | `mark_all_read` | Mark everything read up to `last_read_at`. | |
| 284 | | [`GET /notifications/threads/{id}`](/reference/api/notifications/get-notification-thread/) | `get` | One thread, its last 10 activities, and your subscription. | |
| 285 | | [`PATCH /notifications/threads/{id}`](/reference/api/notifications/mark-thread-read/) | `mark_read` | Mark a thread read, or unread. | |
| 286 | | [`DELETE /notifications/threads/{id}`](/reference/api/notifications/mark-thread-done/) | `done` | Mark a thread done. | |
| 287 | | [`PUT /notifications/threads/{id}/saved`](/reference/api/notifications/save-thread/) | `save` | Save a thread; `DELETE` unsaves it. | |
| 288 | | [`PUT /notifications/threads/{id}/snooze`](/reference/api/notifications/snooze-thread/) | `snooze` | Snooze a thread until `until`; `DELETE` brings it back. | |
| 289 | | [`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`. | |
| 290 | | [`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. | |
| 291 | | [`GET /user/subscriptions`](/reference/api/notifications/list-watched-repos/) | `watched` | The repositories you watch other than the default way. | |
| 292 | |
| 293 | `GET /repos/{owner}/{name}/notifications` and |
| 294 | `PUT /repos/{owner}/{name}/notifications` list and mark one repository's |
| 295 | threads. Every action of the `notifications` tool is in |
| 296 | [MCP tools](/reference/mcp/#notifications). |
| 297 | |
| 298 | For example, to list the reviews waiting on you: |
| 299 | |
| 300 | ```sh |
| 301 | curl "https://api.g1t.sh/notifications?reason=review_requested" \ |
| 302 | -H "Authorization: Bearer $G1T_TOKEN" |
| 303 | ``` |
| 304 | |
| 305 | ## How long items are kept |
| 306 | |
| 307 | Threads you mark done are removed 30 days after you mark them. Any other |
| 308 | thread is removed once nothing has happened on it for 180 days. Saved |
| 309 | threads are kept until you unsave them. |