Documentation

Everything you need to know about configuring and using SAM.

API Reference

Webhook Endpoint

SAM exposes a single webhook endpoint that receives GitHub events.

POST /webhook
Content-Type: application/json
X-Hub-Signature-256: sha256=...

{
  "action": "opened",
  "issue": { ... },
  "repository": { ... }
}

Supported Events

issues.opened - Triggers issue triage
issues.labeled - Triggers development workflow when ready-for-dev label is added
issue_comment.created - Triggers agent responses to comments
pull_request.opened - Triggers PR review

Configuration Options

Repository Configuration

Configure SAM behavior in your repository with .sam/config.yaml:

sam:
  # Enable or disable SAM for this repository
  enabled: true

  # Directory where code changes should be made
  target_directory: "src"

  # Tech stack for context
  tech_stack:
    - "TypeScript"
    - "React"
    - "Node.js"

  # Code conventions
  conventions:
    components: "src/components/"
    tests: "__tests__/"
    styles: "src/styles/"

  # Labels for workflow control
  labels:
    # Label that triggers development
    trigger_dev: "ready-for-dev"
    # Labels for issue types
    feature: "enhancement"
    bug: "bug"
    question: "question"

  # Output directory for generated files
  output_directory: "_sam-output"

Environment Variables

Variable	Description
`GITHUB_TOKEN`	GitHub personal access token or app token
`GITHUB_WEBHOOK_SECRET`	Secret for webhook signature verification
`OPENAI_API_KEY`	OpenAI API key (if using OpenAI)
`ANTHROPIC_API_KEY`	Anthropic API key (if using Claude)
`PORT`	Server port (default: 3000)

Agent Customization

Agent Definition Files

Agents are defined in YAML files located in webhook-server/agents/definitions/:

# sam.yaml
name: Sam
role: Issue Triage Specialist
icon: "🎯"

personality: |
  You are Sam, the Issue Triage Specialist.
  You analyze incoming GitHub issues and classify them
  by type (feature, bug, question) and priority.

instructions: |
  1. Read the issue title and description carefully
  2. Determine the issue type
  3. Assess priority based on impact and urgency
  4. Add appropriate labels
  5. Post a triage summary as a comment

Creating Custom Agents

You can create custom agents by adding new YAML files to the definitions directory. Each agent should have a unique name, role, and set of instructions that define their behavior in the pipeline.

Multi-Repository Setup

Managing Multiple Repositories

SAM can handle multiple repositories from a single server instance. Each repository maintains its own configuration in its .sam/config.yaml file.

• Configure webhooks in each repository pointing to the same SAM server
• Use a GitHub App for easier token management across repositories
• Each repository can have different configurations and conventions
• Agent definitions are shared across all repositories

Deployment Guide

Docker Deployment

The recommended way to deploy SAM is using Docker:

# Build the image
docker build -t sam-webhook-server .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e GITHUB_TOKEN=your_token \
  -e GITHUB_WEBHOOK_SECRET=your_secret \
  -e OPENAI_API_KEY=your_key \
  sam-webhook-server

Cloud Platforms

SAM can be deployed to various cloud platforms:

• Railway - One-click deployment with environment variable support
• Render - Auto-deploy from GitHub with free tier available
• AWS/GCP/Azure - Deploy using container services or VMs
• Self-hosted - Run on your own servers with Docker or PM2

Production Considerations

• Use HTTPS for webhook endpoints
• Set up monitoring and alerting
• Configure rate limiting for API calls
• Use secrets management for sensitive configuration
• Enable logging for debugging and auditing

Need more help?

Check out the GitHub repository for more examples and community support.

View on GitHub