Setup Guide

Get SAM up and running in your repository in just a few minutes.

Prerequisites

Node.js 18 or higher
GitHub account with repository access
OpenAI or Claude API key
Webhook endpoint (public URL or tunnel)
1

Clone the Repository

Clone the SAM repository to your local machine.

git clone https://github.com/saaragh/sam.git cd sam
2

Install Dependencies

Install the required Node.js packages.

cd webhook-server npm install
3

Configure Environment Variables

Create a .env file with your configuration.

# .env
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_WEBHOOK_SECRET=your_webhook_secret

# Choose your AI provider
OPENAI_API_KEY=your_openai_api_key
# or
ANTHROPIC_API_KEY=your_anthropic_api_key

# Server configuration
PORT=3000
NODE_ENV=production
4

Set Up GitHub Webhook

Configure a webhook in your GitHub repository to send events to SAM.

  1. Go to your repository Settings → Webhooks
  2. Click "Add webhook"
  3. Set the Payload URL to your SAM server (e.g., https://your-server.com/webhook)
  4. Set Content type to application/json
  5. Add your webhook secret
  6. Select "Let me select individual events" and choose: Issues, Issue comments, Pull requests
5

Enable SAM in Your Repository

Create a .sam/config.yaml file in your repository to enable SAM.

# .sam/config.yaml
sam:
  enabled: true
  target_directory: "src"
  tech_stack:
    - "TypeScript"
    - "React"
  conventions:
    components: "src/components/"
    tests: "__tests__/"
  labels:
    trigger_dev: "ready-for-dev"
6

Start the Server

Run the SAM server to start processing webhooks.

npm start

SAM is now running! Create an issue in your repository to see it in action.

Troubleshooting

Webhooks not being received?

Check that your server is publicly accessible. For local development, use a tunnel like ngrok or cloudflared.

API rate limits?

Ensure you're using a GitHub token with appropriate permissions. For high-volume repositories, consider using a GitHub App instead of a personal access token.

Agent not responding?

Check the server logs for errors. Make sure your AI API keys are valid and have sufficient credits.

Need more help?

Check out the full documentation or visit our GitHub repository.

Read DocumentationView on GitHub