github-copilot-slack-sdk

Slack bot that bridges Slack threads to GitHub Copilot CLI via the Copilot SDK.

Features

• Thread-safe message queueing with busy notices
• One-click interrupt to stop in-flight runs
• Incoming Slack attachments downloaded and sent to Copilot
• Copilot can return files that upload back to Slack
• Emoji reasoning summaries + live thinking status
• Interactive Block Kit responses (forms, buttons, checklists)

Setup

Prereqs

• Node.js 24+
• Slack app (Socket Mode enabled)
• GitHub Copilot CLI installed on host (or in container)
• Access to a Slack workspace for testing

Install

npm install

First run (onboarding)

npx @tiberriver256/github-copilot-slack-sdk

First run creates:

• bridge.config.yaml
• slack-app-manifest.yaml

If both files exist, onboarding is skipped and the app starts.

Configure

Create .env from docs/config/.env.sample and set required values.

Run (dev)

npm run dev

Run (prod)

npm run start

Environment Variables

Required:

• SLACK_BOT_TOKEN: Bot token (xoxb-*)
• SLACK_APP_TOKEN: App-level token for Socket Mode (xapp-*)
• SLACK_SIGNING_SECRET: Signing secret for request validation

Optional:

• NODE_ENV: development|test|production (default: development)
• HOST: Bind address (default: 0.0.0.0)
• PORT: HTTP port (default: 3000)
• APP_NAME: App name tag (default: github-copilot-slack-sdk)
• LOG_LEVEL: trace|debug|info|warn|error (default: info)
• SLACK_SOCKET_MODE: true|false (default: true)
• SLACK_APP_ID: App ID for diagnostics
• SLACK_CLIENT_ID: OAuth client ID
• SLACK_CLIENT_SECRET: OAuth client secret
• SLACK_REDIRECT_URI: OAuth redirect URI
• SLACK_ALLOWED_CHANNELS: Comma-separated allowlist
• SLACK_ALLOWED_USERS: Comma-separated allowlist
• SLACK_SELF_USER_ID: Optional self-echo guard
• SLACK_ACK_TIMEOUT_MS: Must be < 3000ms (default: 2500)
• COPILOT_CLI_PATH: Copilot CLI path (default: copilot)
• COPILOT_MODEL: Model name (default: gpt-5)
• COPILOT_STREAMING: true|false (default: true)
• COPILOT_SESSION_TIMEOUT_MS: sendAndWait timeout (default: 120000)
• COPILOT_PERMISSION_POLICY: auto|deny|prompt (default: auto)
• BRIDGE_DATA_DIR: Data root (default: ./data)
• BRIDGE_SESSION_STORE_PATH: Session store path override (default: ${BRIDGE_DATA_DIR}/session-store.json)
• BRIDGE_WORKDIR: Copilot workdir (default: ./workspace)
• BRIDGE_SANDBOX: host|docker (default: host)
• BRIDGE_SANDBOX_IMAGE: Docker image (used when BRIDGE_SANDBOX=docker)
• BRIDGE_SANDBOX_NETWORK: Docker network
• BRIDGE_SANDBOX_NAME: Docker container name for attachment copy
• BRIDGE_MCP_ENABLED: true|false (default: false)
• BRIDGE_MCP_CONFIG_PATH: MCP server config file
• BRIDGE_MCP_TOOL_ALLOWLIST: Tool allowlist
• BRIDGE_MCP_TOOL_DENYLIST: Tool denylist
• REDACT_KEYS: CSV list of keys to redact in logs

Troubleshooting

Slack app not responding

• Verify Socket Mode enabled.
• Confirm SLACK_APP_TOKEN starts with xapp-.
• Check bot is installed in the workspace.
• Inspect logs for retry headers and app_rate_limited events.

Ack timeout (>3s)

• Confirm handlers ack() immediately and do heavy work async.
• Check event retries (X-Slack-Retry-Num) and dedupe logic.

Copilot errors

• Validate COPILOT_CLI_PATH and CLI auth session.
• Check CLI version compatibility with SDK.
• Confirm sandbox/working directory permissions.

Session mismatch

• Inspect BRIDGE_SESSION_STORE_PATH for stale or corrupt records.
• Check thread key: channel:threadTs.

Scripts

• npm run dev - run in watch mode with tsx
• npm run build - compile TypeScript to dist/
• npm run start - run the compiled app
• npm test - run Node test runner
• npm run typecheck - type check without emit
• npm run lint - lint TypeScript sources
• npm run format - format with Prettier
• npm run format:check - check Prettier formatting
• npm run check - lint + typecheck + format check

Structure

• src/ - source code
• dist/ - build output
• docs/ - architecture and usage notes

Docs

• docs/config/ENV_SCHEMA.md
• docs/copilot-cli-sdk-bootstrap.md
• docs/slack/slack-app-manifest.yaml
• docs/onboarding.md
• docs/session-store.md