Skip to content

QUICK_START.md

Latest commit

 

History

History
148 lines (112 loc) · 3.87 KB

QUICK_START.md

File metadata and controls

148 lines (112 loc) · 3.87 KB
Raw

GitHub Webhook Secret Validation - Quick Start

What Was Implemented

A startup validation system that ensures GITHUB_WEBHOOK_SECRET is configured before the application starts, preventing unauthorized webhook events.

Key Files

File Type Purpose
backend/src/validation/webhookSecretValidation.ts NEW Validation logic
backend/src/index.ts MODIFIED Calls validation before startup
backend/test/webhookSecretValidation.test.ts NEW 13 comprehensive tests
.env.example MODIFIED Enhanced documentation

How It Works

Production (NODE_ENV=production)

$ NODE_ENV=production npm start
# If GITHUB_WEBHOOK_SECRET is missing:
# Error: GITHUB_WEBHOOK_SECRET environment variable is not configured...
# Exit code: 1

Development (NODE_ENV=development or unset)

$ npm run dev
# If GITHUB_WEBHOOK_SECRET is missing:
# [WARN] startup_validation_warning
# [INFO] server_listen { port: 3001 }

Getting Started

Production Deployment

# 1. Generate secret
SECRET=$(openssl rand -hex 20)

# 2. Set environment
export NODE_ENV=production
export GITHUB_WEBHOOK_SECRET=$SECRET

# 3. Start app
npm start

Local Development

# 1. Copy environment template
cp .env.example .env

# 2. Optional: Set test secret
echo "GITHUB_WEBHOOK_SECRET=test-secret-123" >> .env

# 3. Start dev server
npm run dev

Testing

# Run webhook secret validation tests
npm test -- webhookSecretValidation.test.ts

# Expected: 13 tests, all passing ✓

Error Messages

Production Error

Error: GITHUB_WEBHOOK_SECRET environment variable is not configured.
This is required to verify GitHub webhook signatures and prevent 
unauthorized webhook events. Set GITHUB_WEBHOOK_SECRET to a secure 
random string (e.g., openssl rand -hex 20).

Development Warning

[WARN] startup_validation_warning
  reason: "missing_github_webhook_secret"
  environment: "development"
  message: "GitHub webhooks will not be verified. This is only acceptable in development."

Security Checklist

  • Generate secure secret: openssl rand -hex 20
  • Set GITHUB_WEBHOOK_SECRET in production
  • Set NODE_ENV=production in production
  • Verify .env is in .gitignore
  • Test startup with secret configured
  • Test webhook signature verification
  • Configure GitHub webhook with same secret

Troubleshooting

Problem Solution
"GITHUB_WEBHOOK_SECRET not configured" Set environment variable: export GITHUB_WEBHOOK_SECRET=...
Webhook returns 401 Verify secret matches GitHub webhook settings
Webhook returns 500 Check that secret is set at runtime

Documentation

  • WEBHOOK_SECRET_VALIDATION.md - Complete technical documentation
  • IMPLEMENTATION_SUMMARY.md - Overview and deployment guide
  • WEBHOOK_SECURITY_GUIDE.md - Visual guide with examples
  • CODE_EXAMPLES.md - Complete code reference

Test Results

✅ All 13 tests passing:

  • Production environment: 5 tests
  • Development environment: 4 tests
  • Default environment: 1 test
  • Edge cases: 3 tests

Acceptance Criteria

✅ Production startup fails with clear error if secret missing ✅ Development startup logs warning if secret missing ✅ .env.example documents the variable ✅ Unit tests cover all scenarios ✅ Error messages are clear and actionable ✅ Validation runs before routes/servers initialized ✅ Integrates with existing webhook verification

Next Steps

  1. Review documentation
  2. Deploy to staging
  3. Test webhook verification
  4. Deploy to production with secret configured
  5. Monitor webhook delivery logs
  6. Set up alerts for failures

Support

For detailed information, see:

  • Technical details: WEBHOOK_SECRET_VALIDATION.md
  • Quick overview: IMPLEMENTATION_SUMMARY.md
  • Visual guide: WEBHOOK_SECURITY_GUIDE.md
  • Code reference: CODE_EXAMPLES.md