Documentation
Go to Integrations

GitHub Integration Documentation

Overview

Ticket MATE integrates with GitHub through GitHub Apps to provide repository automation, activity tracking, and notifications for pushes, commits, pull requests, and branch events.

Required Environment Variables

GitHub OAuth App (for User Authentication)

For user authentication via GitHub OAuth:

  • GITHUB_CLIENT_ID - GitHub OAuth App Client ID
  • GITHUB_CLIENT_SECRET - GitHub OAuth App Client Secret

Setup:

  1. Go to https://github.com/settings/developers
  2. Create a new OAuth App
  3. Set Authorization callback URL to: ${NEXTAUTH_URL}/api/auth/callback/github
  4. Copy Client ID and Client Secret to environment variables

GitHub App (for Repository Automation)

For repository automation and webhooks:

  • GITHUB_APP_ID - GitHub App ID (required)
  • GITHUB_APP_PRIVATE_KEY - GitHub App private key (required, can be multiline with \n)
  • GITHUB_APP_SLUG - GitHub App slug/name (optional but recommended)
  • GITHUB_APP_CLIENT_ID - GitHub App OAuth Client ID (required for the Connect GitHub flow; without it, "Connect GitHub" redirects to Settings with an error)
  • GITHUB_APP_CLIENT_SECRET - GitHub App OAuth Client Secret (required for the Connect GitHub flow so the integration persists)
  • GITHUB_WEBHOOK_SECRET - Webhook secret for verifying GitHub webhook signatures (optional but recommended)
  • GITHUB_TOKEN - Personal access token for API calls (optional, for higher rate limits on public repos)

Setup:

  1. Go to https://github.com/settings/apps/new (or edit your existing app)
  2. Configure GitHub App:
    • Name: Your app name
    • Homepage URL: Your app URL (e.g. https://ticket-mate.app)
    • Callback URL (redirect after user authorizes): This must be the API that receives the OAuth code and exchanges it for a token, not the “installed” page.
      • Production: https://ticket-mate.app/api/integrations/github/app/callback
      • Local dev: http://localhost:4000/api/integrations/github/app/callback
      • Do not use /admin/integrations/github/installed here; the app redirects users to that page after the callback.
    • Webhook URL: Either use the canonical endpoint or the legacy path (both work):
      • Canonical: https://ticket-mate.app/api/webhooks/github
      • Legacy (redirects to canonical): https://ticket-mate.app/github/webhook
    • Webhook secret: Generate and save (set as GITHUB_WEBHOOK_SECRET)
    • Permissions: Configure based on your needs
  3. Generate private key and download
  4. Copy App ID from app settings
  5. Set environment variables in Vercel/your hosting platform

Private Key Format: The private key can be stored in environment variables with escaped newlines (\n). The system will automatically unescape them.

Example:

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----\n"

Or with actual newlines (if your environment supports multiline values):

GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA...
-----END RSA PRIVATE KEY-----"

Features

1. GitHub Activity Tracking

View GitHub activity (pushes, commits, PRs, branches) on the activity page:

  • Page: /admin/integrations/github/activity
  • Shows events from connected repositories
  • Filter by event type and repository
  • Links to GitHub for viewing details

2. Notifications

GitHub events create notifications that appear in:

  • Notifications Page: /admin/notifications
  • Notification Types:
    • github_push - Code pushes to repositories
    • github_pr - Pull request events (opened, closed, merged)
    • github_commit - Individual commit events
    • github_branch - Branch creation events

Notifications are automatically filtered by user and include metadata about the event.

3. Webhook Events

The system processes the following GitHub webhook events:

  • installation - GitHub App installation events
  • installation_repositories - Repository selection changes
  • push - Code pushes to repositories
  • pull_request - Pull request events
  • create - Branch/tag creation events

Webhook events are logged to incoming_webhook_logs table for debugging.

Pages

GitHub Integration Page

  • Route: /admin/integrations/github
  • Description: Manage GitHub App installations and configuration
  • Features:
    • View GitHub App configuration status
    • Install GitHub App link
    • List active installations
    • View installation details

GitHub Activity Page

  • Route: /admin/integrations/github/activity
  • Description: View GitHub activity (pushes, commits, PRs, branches)
  • Features:
    • Filter by event type
    • Filter by repository
    • View event details
    • Links to GitHub

GitHub Installed Page

  • Route: /admin/integrations/github/installed
  • Description: Post-installation confirmation page
  • Note: Redirected to after GitHub App installation

API Endpoints

GET /api/integrations/github/installations

Get list of GitHub App installations for the authenticated user.

GET /api/integrations/github/install-url

Get GitHub App installation URL.

GET /api/integrations/github/config

Get GitHub App configuration status.

GET /api/integrations/github/activity

Get GitHub activity notifications for the authenticated user.

POST /api/webhooks/github

GitHub webhook receiver endpoint (no authentication required, uses webhook secret).

Database Schema

GitHubInstallation

Stores GitHub App installation information:

  • installationId - GitHub installation ID
  • ownerType - Organization or User
  • ownerLogin - GitHub username/org name
  • repositorySelection - All repos or selected
  • permissionsJson - App permissions
  • isActive - Installation status

GitHubRepoLink

Links repositories to installations:

  • installationId - Foreign key to GitHubInstallation
  • repoFullName - Repository full name (owner/repo)
  • isActive - Link status

Notification

Stores GitHub activity notifications:

  • type - Notification type (github_push, github_pr, etc.)
  • source - 'GITHUB'
  • title - Event title
  • message - Event description
  • metadata - JSON metadata with event details
  • userId - Associated user ID

Troubleshooting

GitHub App Not Configured

  • Verify all required environment variables are set
  • Check that GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY are correct
  • Ensure private key is properly formatted

Webhooks Not Working

  • Verify GITHUB_WEBHOOK_SECRET matches GitHub App settings
  • Check webhook URL in GitHub App settings: https://ticket-mate.app/api/webhooks/github
  • Check incoming_webhook_logs table for errors

No Activity Showing

  • Ensure GitHub App is installed on repositories
  • Verify repositories are linked in github_repo_links table
  • Check that webhook events are being received (check webhook logs)
  • Verify user is associated with installation account

Authentication Issues

  • For OAuth: Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET
  • Check callback URL matches: ${NEXTAUTH_URL}/api/auth/callback/github
  • Ensure NEXTAUTH_URL is set correctly for your environment

Security Notes

  1. Webhook Verification: Always set GITHUB_WEBHOOK_SECRET to verify webhook signatures
  2. Private Keys: Never commit private keys to git
  3. User Filtering: All notifications are filtered by userId to prevent cross-user data leaks
  4. Environment Variables: Use environment variables for all secrets, never hardcode

Additional Resources