GitHub Access Report Generator

A specialized service for generating comprehensive access reports for GitHub organizations. It provides visibility into which users have access to each repository and their specific permission levels.

Features

• Organization-wide Visibility: View all repositories and who has access to them.
• User-Centric Mapping: See a complete list of users and all repositories they can access.
• High-Scale Support: Designed to handle organizations with 100+ repositories and 1000+ users through pagination and parallel processing.
• Modern UI: Built with Next.js, Tailwind CSS, and Shadcn UI for a responsive and intuitive experience.

How to Run the Project

Prerequisites

• Node.js (v18 or higher)
• pnpm (recommended) or npm/yarn

Setup

1. Install dependencies:

   pnpm install

2. Run the development server:

   pnpm dev

3. Open the application: Navigate to http://localhost:3000 in your browser.

Authentication

The application uses GitHub Personal Access Tokens (PAT) for authentication.

1. Generate a PAT on GitHub (Settings > Developer settings > Personal access tokens > Tokens (classic)).
2. The token requires the following scopes for a full report:
   • repo (Full control of private repositories)
   • read:org (Read organization and team membership)
3. Note: If you use a token with limited permissions, the application will attempt to fall back to publicly available contributor data, which may only show "pull" access.

How to Call the API Endpoint

The application exposes a structured API endpoint for generating reports.

• Endpoint: POST /api/report
• Headers: Content-Type: application/json
• Body:

  {
    "organization": "your-org-name",
    "token": "your-github-pat"
  }

Sample Curl Command

curl -X POST http://localhost:3000/api/report \
     -H "Content-Type: application/json" \
     -d '{"organization": "facebook", "token": "YOUR_GITHUB_PAT"}'

Assumptions and Design Decisions

Parallelization

To handle large organizations efficiently, the application uses Promise.all to fetch collaborator data for all repositories in parallel. This significantly reduces the total time required compared to sequential API calls.

Pagination Handling

The application implements a robust fetchAllPages helper that parses GitHub's Link header to ensure all data is retrieved across multiple pages of results.

Permission Fallback

If the provided PAT doesn't have administrative access to a repository, the API will fail to fetch the collaborators list. In such cases, the service falls back to fetching the public "contributors" list. These users are then mapped with a default "pull" permission to ensure some level of visibility is maintained.

UI Architecture

The frontend uses Next.js Client Components with React's useMemo for efficient searching and filtering of large datasets without re-triggering API calls. s