Setup Guide

This guide walks you through obtaining all required credentials and configuring slack-ticket for your team. The setup process is interactive—simply run slack-ticket setup after obtaining your credentials.

Prerequisites

• Node.js 18.0.0 or higher
• Access to a Slack workspace (with permission to create apps)
• GitHub account with repository access
• AI provider account (OpenAI, Anthropic, or Google)

Step 1: Slack Configuration

Create a Slack App

1. Navigate to the Slack API Dashboard
2. Click Create New App → From scratch
3. Name your app (e.g., slack-ticket) and select your workspace

Configure Bot Scopes

1. In the sidebar, go to OAuth & Permissions
2. Scroll to Scopes → Bot Token Scopes
3. Add the following scopes:

Install the App

1. Click Install to Workspace at the top of the OAuth page
2. Copy the Bot User OAuth Token (starts with xoxb-)
3. Invite the bot to channels where you’ll create tickets: /invite @slack-ticket

Step 2: GitHub Configuration

Create a Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Click Generate new token → Generate new token (classic)
3. Set a descriptive name (e.g., slack-ticket)
4. Select the following scopes:

5. Click Generate token and copy the ghp_... string

Find Your Project ID (Optional)

If you use GitHub Projects, find your Project v2 ID:

# Using GitHub CLI
gh project view <project-number> --org <org-name> --json id

Or leave this field blank during setup—you can add it later or override via CLI flags.

Step 3: AI Provider Setup

Choose one provider that works best for your team:

OpenAI

1. Visit the OpenAI Platform
2. Go to API Keys → Create new secret key
3. Copy the sk-... key

Recommended models: gpt-4o or gpt-4o-mini for balance of quality and cost

Anthropic

1. Go to the Anthropic Console
2. Navigate to API Keys → Create Key
3. Copy your API key

Recommended models: claude-sonnet-4-20250514 or claude-3-5-sonnet-20241022

Google Gemini

1. Visit Google AI Studio
2. Click Get API Key
3. Copy your Gemini API key

Ollama (Local/Self-Hosted)

For teams running Ollama locally:

• Base URL: http://localhost:11434
• Model: Any model you’ve pulled (e.g., llama3, mistral)

Step 4: Run the Setup Wizard

Execute the interactive setup command:

slack-ticket setup

The wizard will prompt you for:

1. Slack Bot Token (xoxb-...)
2. GitHub Personal Access Token
3. GitHub Owner/Organization name
4. Default repository name
5. AI provider selection
6. API key for your chosen provider
7. Model name
8. Default severity level
9. Thread depth (how many messages to fetch, 1-10)

Configuration Storage

Your configuration is stored at ~/.slack-ticket/config.json with secure file permissions (0600 on macOS/Linux).

Step 5: Verify Your Setup

Run the diagnostic command to ensure everything works:

slack-ticket doctor

This checks:

• Slack token validity and channel access
• GitHub token and repository permissions
• AI provider connectivity

Configuration File

After setup, your config.json looks like:

{
  "configVersion": 1,
  "slack": {
    "botToken": "xoxb-..."
  },
  "github": {
    "token": "ghp_...",
    "owner": "your-org",
    "defaultRepo": "your-repo",
    "defaultProject": "PVT_..."
  },
  "ai": {
    "provider": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o",
    "timeoutMs": 30000
  },
  "defaults": {
    "severity": "medium",
    "component": null,
    "threadDepth": 3,
    "imageHandling": true
  },
  "labels": {
    "keywords": { ... },
    "severity": { ... },
    "components": { ... }
  }
}

Customizing Labels

Edit the labels section to match your team’s conventions:

slack-ticket config edit

This opens your config in $EDITOR for manual customization.

Updating Configuration

To update any setting:

# Re-run the setup wizard
slack-ticket setup

# Or manually edit
slack-ticket config edit

# View current configuration
slack-ticket config view

Next: Learn about CLI commands or AI analysis features.