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