oxagenDocs
Connections

Connect Slack

Post each change in a steering repo's health to one Slack channel your organization picks, beside the in-app notice and the email Oxagen already sends.

Overview

When a steering repo loses access or has its settings changed, Oxagen tells the organization's owners in the app and by email. Connect Slack to post the same notice to one channel your team already reads.

One Slack workspace connects to one Oxagen organization. The organization's notices, such as steering repo health, go to the one channel you pick on Organization → Notifications. Each workspace's events go to the channel that workspace picks on the same connection (see Workspace channels). The in-app notice and the email keep going out, so Slack adds a copy and replaces nothing.

Until Oxagen turns on public distribution for its Slack app, Slack installs the app only in Oxagen's own Slack workspace. Slack's install screen refuses any other workspace until then.

Before you start

  • You are an Owner of the Oxagen organization. Only an Owner can connect Slack, pick the organization's channel, or disconnect.
  • You can install apps in the Slack workspace. If your Slack workspace requires approval for new apps, a Slack admin approves the request first.

Connect a Slack workspace

  1. Open Organization → Notifications at /{org}?tab=notifications.
  2. Under Slack, select Connect Slack.
  3. Slack shows the permissions the Oxagen app asks for. Pick your Slack workspace and select Allow.
  4. Slack sends you back to Notifications, which shows the connected Slack workspace.

The connect link lasts ten minutes and works once, for the person who started it. If it expires, select Connect Slack again. If you select Cancel in Slack, Oxagen connects nothing.

Permissions

The Oxagen app asks Slack for four bot scopes.

Slack scopeWhat Oxagen uses it for
chat:writePost the notice
chat:write.publicPost to a public channel without joining it
channels:readList public channels for the channel picker
groups:readList the private channels the Oxagen bot was invited to

Oxagen refuses an install that does not grant chat:write, because it could post nothing.

Pick a channel

  1. Under Slack, choose a channel from the list.
  2. Select Save.

Every public channel appears in the list. A private channel appears only after someone in it invites the bot. Run /invite @Oxagen in the channel, then reload Notifications. Archived channels do not appear. In a Slack workspace with thousands of channels, the list can stop short, and the page says so.

Oxagen posts nothing until you pick a channel.

Workspace channels

The Oxagen bot belongs to the organization, and each workspace picks its own channel on it. The organization's channel keeps the organization's notices, such as steering repo health. A workspace's channel carries the workspace's five events. Workspace notifications lists them.

  1. An Owner connects Slack on Organization → Notifications, as above.
  2. A workspace Admin opens the workspace's notification settings and picks a channel. The list holds public channels only.
  3. A channel shared with another Slack organization does not appear in the list and cannot be picked.

Oxagen asks Slack about the channel when you save, so a channel that was archived or shared after the list loaded is refused. A workspace Admin cannot connect Slack. When the organization has no connection, the Slack section says so in place of the picker and names the Owners who can connect it.

When an Owner selects Disconnect, every workspace's channel is cleared with the connection. Each workspace records why in its audit trail. After you connect Slack again, a workspace Admin picks the channel again.

What Oxagen posts

Oxagen posts one message each time a steering repo's health changes. The message carries the change as a bold title, the health summary under it, and an Open in Oxagen link to the steering repo.

ChangeMessage title
Oxagen can no longer reach the repositoryOxagen lost access to the steering repo <owner/repo>
Someone changed the repository's settingsSettings changed on the steering repo <owner/repo>
The repository recoveredThe steering repo <owner/repo> is healthy again

When a post fails

Some Slack refusals repeat until a person acts. For those, Oxagen stops trying that notice and shows the reason under the channel on Notifications. The in-app notice and the email still go out.

CodeWhat to do
not_in_channelInvite the bot to the private channel with /invite @Oxagen.
channel_not_foundThe channel was deleted, or the bot cannot see it. Pick another channel.
is_archivedUnarchive the channel in Slack, or pick another channel.
token_revoked, invalid_auth, account_inactiveSomeone removed the app from Slack or revoked its token. Select Disconnect, then Connect Slack.
missing_scopeSelect Disconnect, then Connect Slack, so Slack grants every scope the app asks for.
token_unreadableOxagen could not decrypt the stored token. Select Disconnect, then Connect Slack.

Saving a channel clears the recorded failure. So does connecting the same Slack workspace again, which keeps the channel.

Other failures can pass on a retry, such as a timeout, a rate limit, or a Slack server error. For those, Oxagen sends the notice again on the next health check, and it sends all three copies: in the app, by email, and in Slack. So after a Slack outage, owners and admins can receive the same notice twice.

Disconnect

Under Slack, select Disconnect and confirm. Oxagen deletes the stored token, asks Slack to revoke it, and stops posting. The in-app notice and the email keep going out.

If Slack does not answer the revoke, the app can stay installed in your Slack workspace. Remove it from the Slack workspace's app management page.

To send notices to a different Slack workspace, disconnect, then connect again and pick the other workspace.

Security

  • Oxagen encrypts the bot token at rest and stores it on your organization. No agent and no page receives it.
  • The connect link carries a single-use value tied to you and your organization. Oxagen refuses it from anyone else, or after ten minutes.
  • Connecting writes a plugin.credential_set audit event. Disconnecting writes plugin.credential_revoked.

Troubleshooting

ProblemWhat to do
Notifications says Slack is unavailableThis deployment has no Slack app credentials. Contact your Oxagen admin.
Slack says the app cannot be installed in your workspaceThe app is not yet distributed publicly. See the note at the top of this page.
The connect link expired or belongs to someone elseSelect Connect Slack again, and finish in the same browser within ten minutes.
A private channel is missing from the listRun /invite @Oxagen in the channel, then reload Notifications.
No message arrived after a health changeCheck that a channel is picked and read the failure under it on Notifications.

On this page