Notifications and activity
See what needs you in the inbox, by email and from the CLI, follow events live, send webhooks and take back an action.
What needs you
sailfork status
sailfork events --since 2h
sailfork events --follow --types review,comment,ci sailfork status lists what is waiting on you right now. sailfork events prints what happened, and with --follow keeps printing as it happens.
The inbox
/notifications shows All inboxes, with a link to each workspace's inbox and its unread count. /{owner}/inbox shows one: your own (Personal), or an organization you belong to.
The inbox has two tabs, each with a count:
- For you: issues assigned to you, mentions of you, reviews, and caisson writes held for your approval. In an organization's inbox, open pull requests you did not open and have not reviewed lead the list, and choosing one lets you Approve, Approve and merge (when checks pass and nothing holds it back) or Request changes without leaving the inbox.
- Following: comments and status changes on issues you follow, and updates from agents working on them.
Opening a notification takes you to where it happened and marks it read. Mark all read clears the tab. With the keyboard, J and K (or the arrow keys) move through the list and E marks one read.
CI that deployed to an environment, or that you started by hand, tells you when it ends. A mirror that stops or holds back a branch also lands here.
What you follow
You follow an issue when you create it, are assigned to it, comment on it (unless you turn that off) or are @mentioned on it. sailfork issue subscribe 7 and sailfork issue unsubscribe 7 change it from the terminal, and the issue page has a Following control. Mentions are covered in Issues.
The Notifications page in your settings decides what also reaches you by email. Everything lands in the inbox either way.
| Setting | Choices |
|---|---|
| For you (issues assigned to you and mentions) | Email now, Daily digest, Inbox only, Off |
| Following (comments and status changes on issues you follow) | Inbox and email, Inbox only, Off |
| Agent activity (updates from agents on issues you follow) | Inbox and email, Inbox only, Off. With email on, each agent can be muted by name. |
| Follow issues you comment on | On or off |
| A mirror stops or holds back a branch | Inbox and email, Inbox and digest, Inbox only, Off |
| Following and agent email timing | Send now, Daily digest, Hold and send nothing |
| Daily digest arrives at | An hour, in your time zone |
| Quiet hours | Email waits until they end. The inbox keeps filling. |
Security and billing email is always sent.
The activity feed
An organization's Activity page shows the latest pushes, reviews and merges across its repositories, by people and by agents, with who did it and how long ago.
From the CLI
status
sailfork status shows three sections: Your pull requests with their state, checks and review, Waiting for your review, and Assigned to you. It says "Nothing needs you right now." when all are empty, and points at sailfork pr checks when a pull request of yours has failing checks. Each section shows up to 50 rows. -R fenil/ocean-landing limits it to one repository, and --json is for scripts.
events
sailfork events prints reviews, comments, CI, merges and pushes on your repositories.
sailfork events --since 2h
sailfork events --org acme --types review,comment --follow
sailfork events --limit 20 --json | Flag | What it does |
|---|---|
-f, --follow | After the history, keep printing new events until you interrupt it. The cursor to resume from goes to stderr. |
--org <HANDLE> | Every repository of this user or organization, instead of -R or the current clone. |
--types <LIST> | Comma separated: review, comment, ci, mention (mentions of you), merge, push, issue, pull, caisson. |
--since <WHEN> | A cursor printed earlier, an RFC 3339 time, or a duration ago such as 30m, 2h or 7d. Default: the last 30 days, or with --follow only new events. |
--limit <N> | Stop after this many events and print the cursor to continue from. |
Every event printed moves the cursor, so --since <cursor> continues with no gap and no repeat. Events are kept for 30 days. Each event names the repository, the issue or pull request number, the actor, the agent name when an agent acted, and a finer verb such as pull.review, pull.merge or run.fail.
The same feed is GET /api/events for history and GET /api/events/stream for a live text/event-stream. A signed-out request must name a repo or org. See the API reference.
Webhooks
A repository admin can send a signed request to a URL of their own when something happens. Add one in the repository's settings, under Webhooks, or with POST /api/repos/{owner}/{repo}/hooks.
- Events:
push,pull_request(opened, closed, merged, reopened) andci_run(completed). The default is all three. - The URL is
httporhttps, at most 2048 bytes, with no username or password, and must be a public address. Localhost and private addresses are refused. A repository has at most 20 webhooks. - The signing secret (
whsec_...) is shown once, when you create the hook. - Each delivery is a JSON
POSTwithX-Sailfork-Event,X-Sailfork-DeliveryandX-Sailfork-Signature-256, which issha256=and the hex HMAC-SHA256 of the raw body under the secret. - Any 2xx answer is delivered. Anything else, a refused connection or no answer within 10 seconds is retried after 10 seconds, 1 minute, 5 minutes and 30 minutes, then marked failed. Redirects are not followed.
- A
pingdelivery is sent when you create the hook. Deliveries are kept for 30 days and can be redelivered.
curl -X POST https://status.sailfork.com/api/repos/fenil/ocean-landing/hooks \
-H "Authorization: Bearer $SAILFORK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/hook","events":["pull_request","ci_run"]}' Body fields and the rest of the hook routes are in the API reference.
Take back an action
sailfork undo reverses your most recent action:
sailfork undo --dry-run
sailfork undo --yes
sailfork undo --list
sailfork undo 6f1c2a9e-0d4b-4c51-9a77-2f0e8b1d3c55 --yes --list shows your recent actions with their ids and whether each can still be undone (--limit, default 20). --dry-run says what would happen and changes nothing. --yes confirms when there is no terminal to ask on.
What can be undone, within 24 hours and once:
- A comment on an issue or pull request, which is deleted.
- A change to an issue or pull request: labels, assignee, status, close or reopen, title and body, restored to their old values.
- A merge: the base branch moves back, the branch is recreated and the pull request reopens.
- A deleted branch, recreated at its old commit, and a file removed in a caisson, written back.
- A token you created, which is revoked.
Actions are listed for 7 days. An undo is refused with 409 and the reason when the action is older than 24 hours or the thing changed again since. A merge that was not a fast-forward, or that the base branch has moved past, cannot be undone this way, and the message gives the git commands for a revert pull request. Undoing an action twice answers with the first result.
Who sees what
- Your inbox, email settings and
sailfork statusare yours alone. - Anyone who can read a repository can read its events. A token needs
repo:read. - Webhooks, and their deliveries, are for repository admins.
- A person only gets a notification about an issue if they can read the repository.