Slack

Slack is optional: everything else in Revue works without it. Once it's connected, Revue posts in Slack as you, so your messages look like ones you typed yourself. Nothing runs on a server and there's no bot: Revue talks to Slack directly with your own sign-in.

What you get:

• Notify in Slack in the Submit review dialog: a reply in the thread that links the pull request ("@Ann I approved your pull request …").
• A Slack threads tab on every pull request, with Ask for a review.
• Announce in Slack when you open a pull request from Revue.
• Your Slack channels suggested after # in every comment box.
• Message templates you can change, with a live preview, emoji and attached files.

Connect Slack#

1. Open Settings → Accounts and find the Slack card (or click the Slack card on the welcome screen).
2. Click Connect Slack.
3. Click Sign in with Slack. Slack opens in your browser.
4. Pick your workspace and click Allow.
5. Back in Revue, the card shows you (your picture and name) with the workspace.

To add another workspace, click Add Slack workspace on the same card. To remove one, click Sign out next to it and confirm: Revue forgets that workspace's token, and reviews no longer reply in Slack there.

Once a workspace is connected, the card's Slack messages… button opens Settings → Slack messages: who people are on Slack, the default channels and the wording of what Revue posts.

Reply in Slack when you submit a review#

When you submit a review, Revue can reply in the Slack thread where the pull request was shared, tagging its author:

@Ann I approved your pull request web #12 Fix the login form ↗ Revue

The reply says "I approved…", "I requested changes on…" or "I left comments on…", depending on your review.

Guide: Reply in Slack when you approve#

1. Open the pull request and click Submit review….
2. Tick Notify in Slack. Revue looks for the Slack threads that link to the pull request.
3. Reply in shows the thread's channel. If several threads link to the pull request, click the channel to pick another (the one you picked last time is preselected). The arrow button opens the thread in Slack.
4. Tag shows who the reply mentions. People Revue found by their email are just shown; there's nothing to pick. Click + to tag someone else too.
5. Below, the reply appears as Slack will show it. Point at a review button to see its reply; click Edit to change it.
6. Write your review and click Approve. Revue submits the review, then posts the reply in the thread.

The review buttons wait until Revue has found the thread and knows who to tag. The hint under the Slack part says what's missing ("Pick the thread to reply in", "Pick who to tag, or choose No mention").

If the reply fails, your review is still submitted. A notice, The review is in, but the Slack reply failed, shows Slack's error with Retry.

Who gets tagged#

Revue finds the pull request's author on Slack by itself:

1. First, the People on Slack list.
2. Otherwise, the author's email on the code host, looked up in Slack.
3. Otherwise, the one person in your Slack workspace who's plainly them: the same email, the same name before the @ at another address ([email protected] for [email protected]), the same handle as their login, or the same full name. If two people match, it doesn't count.

Someone found by email (steps 2 and 3) is tagged with nothing to choose. If nothing finds them, the Tag line shows Who is on Slack?: click it to see the members of the thread's channel, likely matches first. You can:

• Pick who they are. Revue saves your pick to the People on Slack list, so you're not asked again, and you can click them to pick someone else later.
• Click No mention to name the author in plain text, without tagging anyone.

The Slack threads tab#

With Slack connected, every pull request gets a Slack threads tab (number key 7, after Checks). It lists every Slack thread that links to the pull request, newest first. The tab's label shows how many there are.

Each thread shows:

• the channel (a lock on private ones) and, with several workspaces, the workspace;
• the message that links the pull request and its author;
• when it was posted, and the number of replies when Slack's search gives it;
• Open in Slack.

Click the refresh button (Search Slack again) to search again. If nothing links to the pull request, the tab says No Slack threads link to this pull request.

Ask for a review#

At the top of the Slack threads tab, the Ask for a review button opens a dialog for after you've made changes: ask the people who reviewed before to look again, or ask someone new. The same is behind Request review in the pull request's header (with or without Slack: without it, the review is only requested on the code host).

Guide: Ask for another review after changes#

1. Open your pull request and press 7 (or click Slack threads), then click Ask for a review.
2. In the dialog, check who's picked. People who reviewed before (not you, nor the author) start picked. Click a name to leave them out, or Add to pick someone else.
3. Choose where to ask:
   • Request their review on GitHub (or Bitbucket, Forgejo): asks the code host again, which notifies them.
   • Post in the Slack thread: replies in the thread with a tag for each of them.
4. Check the preview of the Slack message under In Slack it reads. The pencil at its top right changes it by hand (what you write is posted); the arrow beside it goes back to the format.
5. Click Ask for a review, and confirm: the dialog says who's asked, where, and warns about anyone not linked to a Slack person (their tag wouldn't notify them).

The eye next to a picked person ignores them: they're never picked or suggested again (bots, people who've left), on all your computers. The card lists who's ignored, to bring them back.

If someone can't be found on Slack, their name shows Who is it?: click it and pick them among the channel's members (remembered in People on Slack), or choose to name them in plain text.

Open in Slack#

Open in Slack opens the message in Slack's desktop app when it's installed, otherwise in the browser. If the app doesn't start, Revue opens the browser instead and tells you why.

To choose, open Settings → Apps → Slack:

• Open in: Slack app (the default) or Browser.
• Slack app: shows Found Slack at …, or Slack app not found. Type a path or click Choose… to use a Slack that wasn't found, or another build.

Channels in comments#

With Slack connected, every comment box suggests your Slack channels: type # and a letter. This works in review comments and replies, the review's message, a new pull request's description and Jira comments.

• Use ↑ ↓ to move, Enter or Tab to pick, Esc to close.
• Private channels show a lock. With several workspaces, the workspace is shown too.
• The pick goes in as a Markdown link, like [#dev](https://acme.slack.com/archives/C0123). It reads as a link on GitHub, Bitbucket, Forgejo and in Jira, and opens the channel for anyone in the workspace.

A #name you type out that is exactly one of your channels also becomes a link when the comment is posted.

Announce a pull request you open#

When you open a pull request from Revue (see Opening a pull request), the form has Announce in Slack (optional). Pick a channel, public or private, and the form shows exactly What's posted.

By default, with a Jira ticket, that's two messages, as you:

1. In the channel: the ticket's link, for example ABC-123 Document types management.
2. In that message's thread: the pull request and its reviewers, tagged, for example web #42 Document types management @Ann @Bob ↗ Revue.

Without a ticket, it's one message in the channel.

Pull request link text and Ticket link text (above the preview) change what the links read for this announcement only; leave them empty for the default, as the preview shows.

Reviewers are found on Slack like authors: the People on Slack list, then their email. If that doesn't work, the form asks Who is … on Slack? with the channel's members, or No mention to name them in plain text.

Pick Don't post in Slack to skip it for this pull request. If posting fails, the pull request is still open: a notice The pull request is open, but posting in Slack failed shows Slack's error with Retry, which posts only what didn't go through.

The default channel#

You don't have to pick the channel every time. The form starts on a default, which you can set:

• for all repositories, and for each service and account: Settings → Slack messages → Where to post in Slack;
• for one repository: its section in Settings → Repositories, Where to post in Slack.

Any of them except the one for all repositories can also be Don't announce. The form shows where its channel came from ("This repository's default", "Last used for this repository" …).

In the thread of GitHub's message#

When a channel is subscribed to a repository with the GitHub app for Slack (/github subscribe owner/repo), the app posts Pull request opened by … on its own for every new pull request. Turn on Wait for automatic GitHub Slack thread (Settings → Slack messages → Where to post in Slack) and Revue's announcement goes in that message's thread instead of beside it:

1. You open the pull request. The form closes as usual, and a notice says Revue is waiting for GitHub's message.
2. Revue reads the channel's newest messages every 5 seconds until a message from an app links the new pull request (it's recognised by the pull request's address, not by names), for up to a minute.
3. Only the reply is posted in that message's thread: GitHub's message takes the place of the message in the channel, which isn't posted. When the announcement is one message (no ticket, or the two-message switch off), that message goes in the thread.

If GitHub's message doesn't come within the minute, or Revue can't read the channel, the announcement is posted in the channel as before, and a notice says why.

The thread is remembered as the pull request's Slack thread: Notify in Slack in the review dialog and Ask for a review start on it.

It applies to GitHub pull requests only: Bitbucket and Forgejo pull requests are announced in the channel as before.

Reading the channel needs the channels:history scope (and groups:history for a private channel). Accounts connected before Revue asked for them get a note under the switch: sign in to Slack again. Until then, announcements go in the channel.

People on Slack#

Settings → Slack messages → People on Slack tells Revue who someone on a code host is on Slack. Use it for people Revue can't find by email, for example a Bitbucket user who hides theirs.

To add someone:

1. Pick the service (GitHub, Bitbucket or a Forgejo server you're signed in to).
2. Type their login on that service.
3. With several workspaces, pick the workspace.
4. Type their name to find them on Slack, then click Add.

Each row reads like GitHub · ann → @Ann. Click Remove (the × on the row) to delete one. Picks you make on the Tag line of the review dialog appear here too. People you set here always come before an email match.

Message formats#

Settings → Slack messages → Message formats lets you change the wording of everything Revue posts. Each message has its own editor with a Preview that shows it as Slack would, and Reset to default to put the built-in text back.

The messages:

The text is Slack's own formatting ("mrkdwn"): *bold*, _italic_, ~struck~, `code`, <address|text> for a link and :emoji:.

Placeholders#

Words in braces are filled in when the message is posted. The full list is under Placeholders on the settings page.

A placeholder Revue doesn't know is flagged under the editor ("Unknown placeholders, posted as written: …") and posted as you wrote it.

Message language#

Message language picks the language of the built-in texts and the {verdict} words: Same as the app (the default), English or Čeština. It's independent of the language Revue is shown in. A text you changed is posted as you wrote it.

One message or two#

The switch A new pull request with a ticket: the ticket's message, the pull request in its thread is on by default. Turn it off to post both texts as one message in the channel. Without a ticket, the pull request is one message either way.

Ticket keys only#

With Links to a pull request or ticket show only its ticket key on, a pull request's link reads just the ticket key its title has (TMB-1140 in place of web #1203 TMB-1140: ShiftBadge fixes), and a ticket's link just its key. A pull request whose title has no key keeps the long text. Either link's text can also be written by hand when you announce (see above).

Emoji#

:name: emoji are posted as written, and Slack draws them. The preview draws them too: Slack's standard emoji (with skin tones like :wave::skin-tone-3:) and your workspace's own emoji, shown as images.

• Type : and two letters in an editor to get emoji suggestions, your workspace's first (↑ ↓, Enter or Tab, Esc).
• A name that isn't an emoji is flagged under the editor, with a suggestion when it looks like a typo: ":ballon: isn't an emoji in Acme; did you mean :balloon:?"

Attachments#

Each message can be posted with files, such as a celebration GIF on "approved". Click Attach file… above its editor (you can pick several at once), or drop files on the editor. The preview shows a thumbnail of each picture, and the name and size of other files, each with × to remove it.

Files can be up to 10 MB each; a bigger one is refused with a notice. The Open pull request form lists the attachments under What's posted.

If the files can't be posted, the text is posted anyway. A notice, Posted in Slack, but without its files, says why, with Retry to share just the files in the message's thread.

The "↗ Revue" link#

Messages can end with a small ↗ Revue link ({revue_link}) that opens the pull request in Revue for anyone who has it. The switch End messages with a small ↗ Revue link turns it off.

The link is revue://open?url=<pull request address>, which Revue opens once it's registered for revue:// links (Settings → Apps; see Links and opening from anywhere). You can set a web page of your own in the field under the switch instead, one that forwards to Revue.

<!doctype html><meta charset="utf-8"><title>Revue</title>
<script>location.replace("revue://open" + location.search)</script>
<p>Opening the pull request in Revue… If nothing happens, register Revue for
revue:// links (Settings → Apps).</p>

Use your own Slack app#

Revue's own Slack app works for any workspace. If your workspace prefers an app of its own, create one from Revue's manifest.

Guide: Create your own Slack app#

1. In Revue, open Settings → Accounts → Slack and unfold Use your own Slack app.
2. Click Copy app manifest.
3. Go to https://api.slack.com/apps and click Create New App → From a manifest.
4. Pick your workspace and paste the manifest.
5. Under OAuth & Permissions → PKCE, click Opt in.
6. Check that Redirect URLs has http://localhost:47392/callback.
7. Under Basic Information → App Credentials, copy the Client ID.
8. Back in Revue, paste it into Client ID and click Save.
9. Click Sign in with Slack.

Instead of steps 5 to 9, you can click Install to Workspace, copy the User OAuth Token (xoxp-…) from OAuth & Permissions, and paste it under Advanced: use a token instead on the Slack sign-in page.

Leave Client ID empty to sign in with Revue's own app.

{
  "display_information": {
    "name": "Revue",
    "description": "Replies in the Slack thread of a pull request when you review it, and announces the pull requests you open, as you."
  },
  "oauth_config": {
    "redirect_urls": ["http://localhost:47392/callback"],
    "scopes": {
      "user": ["search:read", "chat:write", "channels:read", "groups:read", "users:read", "users:read.email", "emoji:read", "files:write", "channels:history", "groups:history"]
    }
  },
  "settings": { "org_deploy_enabled": false, "socket_mode_enabled": false, "token_rotation_enabled": false }
}

For workspace admins#

• If the workspace requires app approval, people who connect Revue send you a request. Approve Revue under Manage apps → Requests (or your workspace's app management settings). They connect again after that.
• Revue posts only when someone reviewing (or opening a pull request) asks it to, in a thread or channel they picked, as themselves. It reads nothing in the background.
• Restricting the app to some channels doesn't apply: it acts as each user, with their own access.

Privacy: what Revue reads and posts#

• Reads: Slack's search results for a pull request's address, a channel's member list (to pick who to tag), the workspace's people and channels you're in, its own emoji and names; with Wait for automatic GitHub Slack thread on, a channel's newest messages for a minute after you open a pull request, to find GitHub's message about it. All of it is read as you, so you only see what you could see in Slack.
• Posts: only what you ask for (a review reply, a review request, an announcement), where you picked, as you. Link previews are turned off in Revue's messages.
• Keeps: the workspace's people list and its emoji in Revue's cache folder for a day (deleted when you sign out of that workspace), and nothing else from Slack.

See Privacy and security for how Revue stores sign-ins.

Troubleshooting#

For other problems, see Troubleshooting and FAQ.