# Slack

Slack is optional. Connected, it gets one channel per installation where
findings in the `ask` mode wait for approval. Code review stays in GitHub.

## Connect

1. On the settings page, under **Slack**, press **Connect Slack**.
2. Slack asks you to allow the Upseam app and to pick a channel.
3. You return to the settings page, which shows the channel and the workspace
   by name. The channel can be changed there later by picking another one from
   the list.

The list shows the public and private channels Slack returns for the Upseam
bot, to everyone who can change the installation settings (admin on all its
repositories).

If you connected Slack before Upseam asked to read channel names, the settings
page shows a channel id field and a note to reconnect. Press **Reconnect
Slack** once to pick channels by name; until then reports and buttons work as
before.

We recommend a private channel for your team, because anyone in the
workspace who can press a button there can approve a finding (see below). For a private channel, invite
the Upseam bot.

## Messages

Messages name files and line numbers, never code.

- **Approval.** One message for each finding that waits for approval: in the
  [`ask` mode](delivery-modes.md), and successor-model and Dependabot or
  Renovate findings in any mode. It says what changed, where it touches your
  code and what Upseam can do, with **Open PR**, **Snooze 7 days** and
  **Ignore**. For a Dependabot or Renovate bump, it also warns that your CI
  will run the bot's commits with your repository secrets.
- **Successor model that needs you.** When a successor-model finding needs
  you, for example because the vendor names several replacements, a message
  says so, without buttons.
- **Setup.** When fixes are generated in your GitHub Actions and the
  `upseam-generate` workflow is missing, one message says what to add.
- **Updates.** After a button press the same message shows the result: the
  pull request with who approved it and its CI result, snoozed until a date,
  ignored, merged or closed. If the patch fails the gates, the message says
  Upseam could not make a safe fix and points to the dashboard issue.

Pull requests opened in the `auto` mode and other findings that need you are
not posted to Slack; they are in the dashboard issue and your pull requests.
Before a model is connected, fixable findings are posted as information
messages with an **Open settings** button instead of approval buttons; see
[Without a model](models.md#without-a-model).

## Who can press the buttons

Slack users are not linked to GitHub users, so Upseam does not check GitHub
access for button presses. Any full member of the connected workspace can
press a button. Clicks from guests, bots, deleted users and users of another
workspace are refused.

- **Open PR** makes Upseam write the patch and push `upseam/<group>`. Your CI
  then runs that branch with your repository secrets before anyone reviews the
  pull request. Merging stays in GitHub, under your branch rules.
- **Snooze 7 days** hides the finding for a week.
- **Ignore** switches the finding off for good; there is no undo.

## Permissions

| Scope               | Why                                                  |
| ------------------- | ---------------------------------------------------- |
| `channels:read`     | List public channels so you can pick one by name.    |
| `chat:write`        | Post and update messages.                            |
| `chat:write.public` | Post to a public channel without an invitation.      |
| `groups:read`       | List private channels so you can pick one by name.   |
| `incoming-webhook`  | Let you pick the channel when you connect.           |
| `users:read`        | Refuse clicks from guests, bots and deleted users.  |

Upseam reads channel names and ids to fill the picker. It does not read
channel history. The bot token is stored encrypted, the same way as a
[model key](models.md#key-stored-with-upseam).

## Disconnect

**Disconnect Slack** on the settings page revokes the bot token with Slack and
deletes the link. Removing the app from your workspace in Slack does the same.