Documentation


Octobox helps you triage notifications efficiently so you can spend less time managing and more time getting things done.

If you manage more than one active project on GitHub, you probably find GitHub Notifications pretty lacking. Notifications are marked as read and disappear from the list as soon as you load the page or view the email of the notification. This makes it very hard to keep on top of which notifications you still need to follow up on. Most open source maintainers (and some GitHub staff) end up using a complex combination of filters and labels in their mail client to manage their notifications from their inbox. If, like us, you try to avoid email, then Octobox is for you.

Accessing Octobox


This instance of Octobox is hosted by the Octobox.io team. To access Octobox.io you just need to sign in with your GitHub profile or install the GitHub app on the homepage.

Signing in with GitHub

This will give you access to basic notification information for public and private repositories using GitHub's notification scope. To access more detailed information you need to install the Octobox.io GitHub App.

Installing the GitHub App

To access more detailed information about your notifications (assignees, labels, conversations threads etc) Octobox.io needs more privileged access to your repositories. To enable this you need to install our GitHub App for your personal or organisation's account. Access to public repositories on Octobox.io is free forever, access to private repositories is a paid-for service.

Paying for private repository access

There are two ways to pay for private repo access on Octobox.io:

  • By making a donation of X or more each month to the Octobox community through Open Collective
  • By paying X per Y through the GitHub Marketplace, which is charged monthly to your GitHub account.

This may seem a little strange, but bear with us: As a social experiment in open source sustainability we are asking you to make a choice between supporting the community of maintainers and contributors, or supporting the commercial entity that operates Octobox.io. The service you'll receive will be exactly the same regardless of the way you pay. You can read more about why we think this is important over on our blog.

Host your own Octobox

Alternatively you can host your own instance of Octobox. See the installation guide for instructions and details regarding deployment to Heroku, Docker, and more.

Using Octobox


Octobox helps you triage notifications from GitHub. If you use GitHub's own notifications dashboard you'll be familiar with some of the interface, actions etc. but there are some important differences:

Archiving

Octobox extends GitHub's notification model by providing an additional 'archived' status, much like Gmail's email client. Archived notifications will not appear in your inbox again unless the thread, issue or PR receives a new notification. Archiving a notification does not result in any action on GitHub.

Starring

Octobox also adds a starred status to help you highlight important notifications with a star so you can come back and find them easily. Starred notifications are not social, they are more like bookmarks that GitHub stars. Starring a notification does not result in any action on GitHub.

Muting

Muting a notification will mark the notification as read, move it to the archive and ignore all further notifications from this thread, issue or PR. Muting also sets the thread to ignore:true ignoring further notifications on GitHub too.

Syncing

By default Octobox will synchronise every time you hit the synchronise button. You can set automatic refresh interval on the settings page.

Shortcuts


Octobox features a full set of keyboard shortcuts inspired by Gmail:

.
or
r
Refresh
j
Move down the list
k
Move up the list
s
Star current notification
x
Mark current notification
a
Select/deselect all
y
or
e
Archive current/marked notification(s)
m
Mute current/marked notification(s)
d
Mark current/marked notification(s) as read here and on GitHub
#
Delete current/marked notification(s)
o
or
Enter
Open current notification in a new window
?
Show this help menu
esc
Close modal, thread OR clear filters

The sidebar contains most of the things you'll need to navigate between views in Octobox:

Archived Notifications that you've archived won't appear in your inbox again until Octobox receives another notification regarding that thread, issue or PR.
Starred Notifications that you've starred are gathered together so you can come back and find them easily.
Read/unread Notifications that have yet to be read or have been read, respectively. Nothing new here.
Type Notifications by type (commit, issue, pull request, release, etc)
Reason Notifications by the reason you've received it (assigned, authored, commented, mentioned, review requested, state changed or subscribed).
Org/repo Notifications from a particular organisation and/or repo.
State The state of the underlying issue or PR. i.e. open, closed, merged,
Assignee Notifications assigned to you.
Status The current CI status of the underlying PR. i.e. Success, Failing, Pending
Bots Notifications created by bots.
Unlabelled Notifications that have not been labeled.
Visibility Notifications from public or private repositories.

Searching Octobox


Octobox's search bar supports the following filter prefixes. Combine them together and with free text searches, for example: "github enterprise type:issue owner:octobox reason:assign":

Many prefixes accept multiple arguments when separated by commas or passed twice, for example:
"type:issue,release owner:octobox owner:24pullrequests".

Some prefixes also can be negated to exclude certain types of results, for example:
"-repo:splitrb/split -type:commit -owner:octobox -reason:mention".

Supported prefixes
repo:octobox/octobox Only search notifications from the octobox/octobox repository.
owner:microsoft Only search notifications from repos in the microsoft organisation.
type:pull_request Only search pull requests. Also accepts: issue, release, commit, repository_invitation and repository_vulnerability_alert.
number:123 Filter by notifications from issues and/or pull requests with the number '123'.
reason:mention Filter by reason the notification was triggered. Also accepts: comment, author, state_change, assign, subscribed, team_mention, security_alert.
starred:true Search notifications that you've starred. Also accepts false for the inverse.
archived:true Search notifications that you've archived. Also accepts false for the inverse.
inbox:true Search notifications in your inbox. Also accepts false for the inverse.
unread:true Search unread notifications. Also accepts false for the inverse.
muted:true Search muted notifications. Also accepts false for the inverse.
sort:updated Sort notifications by updated, read or subject.
order:asc Sort notifications in ascending (asc) or descending (desc) order. Use with sort.
state:open Filter by notifications from issues or pull requests that are open. Also accepts closed and merged.
label:bug Filter by notifications from issues or pull requests with the label of 'bug'.
author:andrew Filter by notifications from issue or pull requests that were created by 'andrew'.
status:success Filter by notifications from pull requests where checks status is 'success'. Also accepts failure, pending and error.
unlabelled:true Search notifications that don't have any labels.
bot:true Search notifications generated by GitHub apps or bot users (name ends in '-bot').
private:true Search notifications from private repositories. Also accepts false for the inverse.
assignee:andrew Filter by notifications from issue or pull requests that are assigned to 'andrew'.
locked:true Search for lock conversations. Also accepts false for the inverse.
draft:true Search for only draft pull requests. Also accepts false for the inverse.

API Documentation


Access to the Octobox API requires a key which you can generate and regenerate from the settings page.

Support


Octobox.io is a small community of people supporting the service. We do not offer formal support processes. If you require formal support arrangements please email us otherwise you can try: