Connect a Slack bot to GitHub

Verified August 11, 2026

This gives a Slack bot access to GitHub. Ask it a question in a channel and it will read issues, pull requests, and code in your repositories and answer in the thread.

What you need

  • A Slack workspace where you can install apps
  • A GitHub account
  • An OpenRouter account

Install the CLI

npm i -g @substructure.ai/cli

Write the config

Save this as substructure.toml.

substructure.toml
name = "repo-bot"

[llm.openrouter]
type = "openrouter"

[mcp.github]
url = "https://api.githubcopilot.com/mcp/"
auth = "token"

[agent.repo]
llm = "openrouter"
model = "z-ai/glm-5.2"
system = "You are the repo assistant. Answer questions about issues and pull requests."
mcp = [{ id = "github", tools = { include = ["*issue*", "*pull_request*"] } }]

[slack]
dm = "repo"
mentions = "repo"

[remote]
url = "https://api.substructure.ai"

[agent.repo] declares the agent: its model, its prompt, and the connections it can reach. The Slack bot is how you talk to it.

The file holds the server URL and the agent that uses it. It holds no tokens.

[remote] is the deployment the CLI talks to. subs apply writes the org and the project back under it.

Create the project

subs apply

This creates the project from the file and writes the project id back into it. If you are not signed in yet, the command opens your browser first. Run subs apply again after any edit to the file.

Add your LLM key

subs llm set-key openrouter

The agent's model runs through OpenRouter, so it needs an OpenRouter API key. Create one at openrouter.ai/keys if you do not have one. The command stores the key with your deployment. It never goes in the config file.

Authorize GitHub

gh auth token | subs mcp set-token github

The token is read from the pipe or the variable. It never appears in the command line or in the config file.

Run subs mcp list to check the connection is authorized.

Connect Slack

subs slack connect

Pick your workspace and approve. The bot is live once the command prints the workspace name.

Ask it something

Invite the bot to a channel and mention it.

  • "what pull requests are waiting on review?"
  • "summarise issue 412"

Each tool call shows in the thread as a task card. Open a card to see the arguments and the result.

Why the tool filter

The GitHub server offers a large number of tools. This keeps the list to issues and pull requests.

A model picks worse as the tool list grows, and worst between tools that look alike. The filter belongs to the agent, so two agents can share one connection and see different tools.

substructure.toml
[agent.repo]
mcp = [{ id = "github", tools = { include = ["*issue*", "*pull_request*"] } }]

If it does not answer

  • Connection not authorized. Run subs mcp list. A declared connection with no credential reaches nothing.
  • No [slack] section. A connected workspace with no [slack] never replies.
  • Bot not invited. Invite it to the channel before you mention it.
  • Tools missing. The engine fetches the tool list once per session. Start a new thread after you change the filter.
  • Anything else. Run subs doctor.

Add another server

Declare it and name it on the agent.

substructure.toml
[mcp.github]
url = "https://api.githubcopilot.com/mcp/"

[mcp.linear]
url = "https://mcp.linear.app/mcp"

[agent.repo]
mcp = ["github", "linear"]

Tools arrive prefixed with the connection id, such as github__search.

The same setup works for Sentry, Linear, Notion, Stripe, and each has its own guide. See all guides.

Next steps