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
- Open Organization → Notifications at
/{org}?tab=notifications. - Under Slack, select Connect Slack.
- Slack shows the permissions the Oxagen app asks for. Pick your Slack workspace and select Allow.
- 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 scope | What Oxagen uses it for |
|---|---|
chat:write | Post the notice |
chat:write.public | Post to a public channel without joining it |
channels:read | List public channels for the channel picker |
groups:read | List 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
- Under Slack, choose a channel from the list.
- 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.
- An Owner connects Slack on Organization → Notifications, as above.
- A workspace Admin opens the workspace's notification settings and picks a channel. The list holds public channels only.
- 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.
| Change | Message title |
|---|---|
| Oxagen can no longer reach the repository | Oxagen lost access to the steering repo <owner/repo> |
| Someone changed the repository's settings | Settings changed on the steering repo <owner/repo> |
| The repository recovered | The 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.
| Code | What to do |
|---|---|
not_in_channel | Invite the bot to the private channel with /invite @Oxagen. |
channel_not_found | The channel was deleted, or the bot cannot see it. Pick another channel. |
is_archived | Unarchive the channel in Slack, or pick another channel. |
token_revoked, invalid_auth, account_inactive | Someone removed the app from Slack or revoked its token. Select Disconnect, then Connect Slack. |
missing_scope | Select Disconnect, then Connect Slack, so Slack grants every scope the app asks for. |
token_unreadable | Oxagen 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_setaudit event. Disconnecting writesplugin.credential_revoked.
Troubleshooting
| Problem | What to do |
|---|---|
| Notifications says Slack is unavailable | This deployment has no Slack app credentials. Contact your Oxagen admin. |
| Slack says the app cannot be installed in your workspace | The app is not yet distributed publicly. See the note at the top of this page. |
| The connect link expired or belongs to someone else | Select Connect Slack again, and finish in the same browser within ten minutes. |
| A private channel is missing from the list | Run /invite @Oxagen in the channel, then reload Notifications. |
| No message arrived after a health change | Check that a channel is picked and read the failure under it on Notifications. |
Connect GitLab
Keep a workspace's steering repo on gitlab.com. Steering PRs open as merge requests, checked and merged the way they are on GitHub.
Import agent configuration
Link a repository and Oxagen finds its CLAUDE.md, AGENTS.md, rules, skills, commands, subagent files and MCP configs, turns them into steering records, and opens one steering PR.