GitHub Integration

Configure Sugar to automatically discover work from GitHub issues and pull requests.

Authentication Methods

Sugar supports three authentication methods for GitHub integration:

Method 1: GitHub CLI (Recommended)

Uses your existing gh CLI authentication - easiest if you already use GitHub CLI.

Prerequisites:

# Install GitHub CLI
# macOS: brew install gh
# Windows: winget install GitHub.cli

# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status

Configuration:

sugar:
  discovery:
    github:
      enabled: true
      repo: "username/repository"
      auth_method: "gh_cli"

      gh_cli:
        command: "gh"
        use_default_auth: true

      issue_labels: ["bug", "enhancement", "sugar-task"]
      check_interval_minutes: 30

Benefits:

• Uses existing gh authentication
• No need to create personal access tokens
• Supports all GitHub CLI features

Method 2: Personal Access Token

Uses a GitHub Personal Access Token for authentication.

Setup Token:

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Generate new token (classic) with scopes: repo (private) or public_repo (public)
3. Copy the token

Configuration:

sugar:
  discovery:
    github:
      enabled: true
      repo: "username/repository"
      auth_method: "token"
      token: "ghp_your_token_here"

      issue_labels: ["bug", "enhancement"]
      check_interval_minutes: 30

Using Environment Variable (Recommended):

# Set environment variable
export GITHUB_TOKEN="ghp_your_token_here"

# In config, leave token empty - Sugar will use $GITHUB_TOKEN
token: ""

Method 3: Auto-Detection

Tries GitHub CLI first, falls back to token if CLI isn't available.

sugar:
  discovery:
    github:
      enabled: true
      repo: "username/repository"
      auth_method: "auto"

      # Token fallback (optional)
      token: ""  # Or set GITHUB_TOKEN environment variable

      gh_cli:
        command: "gh"
        use_default_auth: true

Configuration Options

sugar:
  discovery:
    github:
      enabled: true
      repo: "username/repository"
      auth_method: "auto"           # "token", "gh_cli", or "auto"

      # Token authentication
      token: ""                     # Personal access token

      # GitHub CLI authentication
      gh_cli:
        command: "gh"
        use_default_auth: true
        timeout_seconds: 30

      # Discovery settings
      issue_labels: [               # Labels to monitor
        "bug",
        "enhancement",
        "good-first-issue",
        "sugar-task"
      ]

      check_interval_minutes: 30    # How often to check
      max_issues_per_check: 10      # Limit per check

      # Task creation
      auto_create_tasks: true       # Auto-create tasks from issues
      default_priority: 3           # Default task priority
      label_priority_map:           # Map labels to priorities
        "critical": 5
        "bug": 4
        "enhancement": 3

Label Filtering

Sugar can filter issues by labels to only pick up relevant work:

sugar:
  discovery:
    github:
      issue_labels: ["sugar-task", "ai-ready"]
      exclude_labels: ["wontfix", "duplicate", "invalid"]

Automatic Task Creation

When Sugar finds matching issues, it can automatically create tasks:

# GitHub Issue:
# Title: Fix login timeout bug
# Labels: bug, critical

# Sugar creates:
# Task: Fix login timeout bug
# Type: bug_fix
# Priority: 5 (from label_priority_map)

Workflow

1. Create GitHub Issue with appropriate labels
2. Sugar discovers the issue during its check cycle
3. Task created in Sugar's queue with mapped priority
4. Sugar executes the task autonomously
5. Issue updated with progress (if configured)

Troubleshooting

GitHub CLI Not Found

# Install GitHub CLI
brew install gh

# Or specify full path in config
gh_cli:
  command: "/usr/local/bin/gh"

Authentication Errors

# Re-authenticate with GitHub CLI
gh auth logout
gh auth login

# Verify authentication
gh auth status

Token Permissions

Ensure your token has the required scopes:

• repo - For private repositories
• public_repo - For public repositories only
• read:org - For organization repositories