Setup GitHub Login with Next.js Pages Router, Supabase & GitHub API Integration Tutorial

🚀

TLDR - What You'll Build!

Build a production-ready GitHub-integrated SaaS application with secure OAuth authentication, repository management, pull request automation, and workflow control using modern React stack.

📋 What You'll Learn

GitHub OAuth integration with Supabase authentication

Repository management (create, update, delete, sync)

Pull request automation (create, manage, track status)

GitHub Actions workflow control and monitoring

Real-time data synchronization with TanStack Query

Type-safe development with TypeScript and Zod validation

Production deployment with security best practices

🛠️ Tech Stack

Frontend: Next.js (Pages Router), TypeScript, Tailwind CSS, Shadcn/UI

Backend: Supabase (Auth + Database), Prisma ORM

State Management: Zustand + TanStack Query

Forms: React Hook Form + Zod validation

GitHub API: Octokit REST client

Deployment: Vercel-ready configuration

⚡ Key Features

✅ Secure GitHub OAuth with token management

✅ Repository CRUD operations synced with GitHub

✅ Pull request creation and management

✅ GitHub Actions workflow automation

✅ Real-time updates and caching

✅ SaaS-ready with feature flags and plan restrictions

✅ Production security with rate limiting and validation

✅ Comprehensive testing utilities and guides

👥 Who This Is For

New projects: Complete step-by-step setup from scratch

Existing projects: Migration guide for Next.js + Supabase apps

Skill level: Intermediate (React/TypeScript knowledge required)

Time investment: 4-6 hours for full implementation

🎯 End Result

A fully functional GitHub SaaS platform where users can authenticate with GitHub, manage repositories, create pull requests, trigger workflows, and collaborate - all within your custom application interface.

Includes: Test users, cURL testing commands, debugging utilities, and production deployment guide.

Perfect for developers building developer tools, project management platforms, or any SaaS requiring GitHub integration.

Introduction

This comprehensive tutorial guides developers through building a production-ready GitHub-integrated SaaS application using Next.js Pages Router, Supabase authentication, and modern React development tools. Learn to implement secure OAuth authentication, manage GitHub repositories, handle pull requests, and automate workflows while maintaining type safety and optimal performance.

The architecture combines Next.js Pages Router for its mature ecosystem and straightforward API routes, Supabase for authentication and real-time database capabilities, and GitHub's REST API for comprehensive repository management.

What You'll Build

Secure GitHub OAuth authentication

Repository management (list, create, update, delete)

Pull request creation and management

Workflow automation

Real-time updates

Type-safe operations

Production-ready architecture

Prerequisites

Required Knowledge

React and TypeScript fundamentals

Next.js basics (Pages Router)

Git and GitHub workflow

Basic understanding of OAuth 2.0

Required Accounts & Tools

Node.js 18.18 or later

npm, yarn, or pnpm package manager

A GitHub account with developer access

A Supabase account for backend services

Git for version control

New Project Setup

Creating the Next.js Project

Configure with these settings when prompted:

TypeScript: Yes

ESLint: Yes

Tailwind CSS: Yes

src/ directory: Yes

App Router: No (We're using Pages Router)

Import alias: Yes (@/*)

Installing Dependencies

Project Structure

Existing Project Migration

Compatibility Check

Before starting, verify your existing project has:

Migration Steps

1. Update Dependencies

2. Environment Variables Audit

Check your existing .env.local and add missing variables:

3. Database Schema Migration

If you have existing Prisma schema, add the GitHub-related models:

4. Supabase Database Update

Run these SQL commands in your Supabase SQL editor:

GitHub OAuth Configuration

Step 1: Create GitHub OAuth Application

Navigate to GitHub Settings → Developer settings → OAuth Apps

Click "New OAuth App"

Configure:

Application name: "Your SaaS App Name"

Homepage URL: http://localhost:3000 (development)

Authorization callback URL: https://your-project.supabase.co/auth/v1/callback

Application description: Brief description

Important Security Notes:

Store credentials securely

Never commit secrets to version control

Use different OAuth apps for development/production

Step 2: Required OAuth Scopes

For comprehensive GitHub integration, request these scopes:

Supabase Backend Setup

Step 1: Enable GitHub Authentication

Go to Authentication → Providers in Supabase dashboard

Enable GitHub provider

Enter OAuth credentials:

GitHub Client ID: From your OAuth app

GitHub Client Secret: Generated secret

Copy the Callback URL to your GitHub OAuth app

Step 2: Database Schema

Complete Prisma Schema

Supabase SQL Setup

Next.js Application Configuration

Environment Variables

Environment Validation

Supabase Client Setup

Prisma Setup

Authentication Implementation

Authentication Hook

Auth Callback Page

Login Page

State Management

Zustand Auth Store

GitHub Data Store

GitHub API Integration

Enhanced GitHub Client

Testing & Debugging

Test Users Setup

API Testing Utilities

Human Testing Guide

Security & Best Practices

Rate Limiting & Error Handling

Input Validation & Sanitization

Deployment Guide

Vercel Deployment

Production Environment Setup

Troubleshooting Common Issues

1. Authentication Issues

Problem: GitHub OAuth redirect not working Solution:

Verify callback URL matches exactly in GitHub OAuth app

Check Supabase provider configuration

Ensure environment variables are correct

Problem: Session not persisting Solution:

Check localStorage permissions

Verify Supabase client configuration

Check middleware implementation

2. API Issues

Problem: GitHub API rate limiting Solution:

Problem: Database connection errors Solution:

Verify DATABASE_URL format

Check Supabase connection limits

Review Prisma schema

3. UI Issues

Problem: Components not rendering Solution:

Check console for JavaScript errors

Verify all imports are correct

Ensure Tailwind classes are available

Problem: Responsive design issues

Solution:

Test on multiple screen sizes

Use Tailwind responsive prefixes

Check CSS conflicts

Feature Flags & SaaS Integration

Final Implementation Checklist

GitHub OAuth app configured

Supabase authentication enabled

Database schema created

Environment variables set

Authentication flow working

Repository management functional

Pull request creation working

Error handling implemented

Rate limiting configured

Security headers added

Test users created

API endpoints tested with cURL

Mobile responsiveness verified

Production deployment completed

GitHub OAuth production URLs updated

🚀

Conclusion!

This tutorial provides a complete, production-ready implementation with proper error handling, security measures, testing utilities, and migration guidance for existing projects. The code is thoroughly commented and includes debugging utilities that can be toggled for production use.

🎁 Bonus - Appendix 1: 📋 Testing & Validation

🚀

Testing & Validation Guide

Testing Commands & Validation Guide

Quick API Testing with cURL

1. Get User Token

2. Test Authentication

3. Test Repository Endpoints

4. Test Pull Request Endpoints

Human Testing Checklist

Authentication Flow

Navigate to /auth/login

Click "Continue with GitHub"

Complete OAuth on GitHub

Verify redirect to /dashboard

Check user profile in Supabase dashboard

Test logout functionality

Repository Management

Access /repositories page

Verify repositories load from GitHub

Test search functionality

Test filters (public/private, language)

Create new repository

Update repository settings

Delete test repository

Pull Requests

Select repository with branches

Create new pull request

Verify PR appears in GitHub

Check PR status updates

Close/merge PR from app

Error Handling

Test with invalid token

Test with expired session

Test API rate limiting

Test network failures

Test malformed requests

Mobile/Responsive

Test on mobile devices

Verify responsive design

Test touch interactions

Check accessibility

Debugging Commands

Check Environment Setup

Database Validation

Application Health Check

Performance Testing

Load Testing

Memory Monitoring

Security Testing

Check Security Headers

Validate Input Sanitization

Rate Limit Testing

🎁 Bonus 2: 🤖 AI Coding Agent Implementation Guide

🚀

A comprehensive instruction manual for AI coding agents implementing GitHub integration following this tutorial

🎯 Guide Overview

This guide provides structured instructions for AI coding agents to successfully implement the GitHub integration tutorial while working collaboratively with human developers. It ensures proper implementation, identifies manual tasks, and establishes clear communication protocols.

📋 Pre-Implementation Analysis Protocol

Phase 1: Project Assessment

AI Agent Instructions: Before starting implementation, perform a comprehensive analysis and report findings to the human:

3. Project Structure Analysis

Router type: Pages Router App Router Mixed

TypeScript: Yes No Partial

Existing auth system: None NextAuth Supabase Custom Other: ___

Database: None Prisma Supabase PostgreSQL Other: ___

State management: None Redux Zustand Context Other: ___

4. Required Manual Tasks Identified

[List all tasks that require human intervention]

5. Recommended Implementation Approach

[Provide step-by-step approach based on analysis]

2. Supabase Project Setup

3. Environment Variables Setup

4. Production Deployment

🔄 Implementation Workflow

Phase 2: Systematic Implementation

AI Agent Instructions: Follow this structured approach:

Step 1: Environment & Dependencies

Step 2: Database Schema Implementation

Step 3: Authentication Implementation

Step 4: GitHub API Integration

Step 5: UI Components Implementation

🔍 Quality Assurance Protocol

Phase 3: Testing & Validation

AI Agent Instructions: Execute comprehensive testing and request human validation:

Automated Testing Setup

Security Validation

🤝 Communication Protocols

AI-Human Interaction Guidelines

AI Agent Instructions:

1. Progress Reporting

2. Error Reporting

3. Decision Points

📚 Adaptation Guidelines

Handling Different Project Configurations

AI Agent Instructions: Adapt implementation based on project variations:

Existing Authentication Systems

Different Database Setups

Framework Variations

🔧 Troubleshooting Protocol

AI Agent Instructions for Common Issues:

1. Authentication Issues

2. API Integration Issues

3. Database Issues

📋 Final Handoff Checklist

Phase 4: Completion & Documentation

AI Agent Instructions: Before considering implementation complete:

1. Code Quality Review

2. Feature Completeness

3. Deployment Readiness

4. Documentation Package

🎯 Success Criteria

Implementation Success Metrics

AI Agent Instructions: Validate these criteria before marking complete:

Technical Success

All tests pass (manual and automated)

No TypeScript/build errors

Performance meets requirements

Security vulnerabilities addressed

Mobile responsiveness verified

Functional Success

Users can authenticate with GitHub

Repository operations work correctly

Pull requests can be created/managed

Workflows can be triggered

Error states handled gracefully

Integration Success

Fits seamlessly with existing codebase

Doesn't break existing functionality

Follows project conventions

Documentation is comprehensive

Team can maintain the code

User Experience Success

Intuitive user interface

Fast loading times

Clear error messages

Mobile-friendly design

Accessible to all users

🤖 AI Agent Quick Reference

Essential Commands for AI Agents

Critical Files Checklist

This guide ensures AI coding agents can successfully implement the GitHub integration tutorial while maintaining clear communication with human developers and identifying tasks that require manual intervention.