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_PATH - Path to the GitHub App private key PEM file (required, e.g. ./secrets/github-app-private-key.pem)
  • 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: Set in GitHub App to the value of GITHUB_WEBHOOK_URL from env (e.g. https://ticket-mate.app/api/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: Store the PEM file on disk and set GITHUB_APP_PRIVATE_KEY_PATH to its path (e.g. ./secrets/github-app-private-key.pem). The file should contain the full PEM including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----. Do not commit the key file; add *.pem or the secrets directory to .gitignore.

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/github/webhook (and /api/webhooks/github)

GitHub webhook receiver. Configure your GitHub App Webhook URL to GITHUB_WEBHOOK_URL (e.g. https://ticket-mate.app/api/github/webhook). No authentication required; uses GITHUB_WEBHOOK_SECRET for signature verification.

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_PATH 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 matches GITHUB_WEBHOOK_URL (e.g. https://ticket-mate.app/api/github/webhook)
  • 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