A production-quality Spring Boot service that connects to the GitHub API and generates a report showing which users have access to which repositories inside a GitHub organization.
Built for reliability, scalability, and clean API design.
Organizations often need visibility into who has access to which repositories across their GitHub organization.
This service connects to the GitHub REST API and generates an aggregated access report mapping users to the repositories they can access.
It is designed to scale efficiently even for large organizations with:
- 100+ repositories
- 1000+ collaborators
The service exposes a clean REST API that returns the report in structured JSON format.
| Feature | Description |
|---|---|
| GitHub API Integration | Connects securely to GitHub using a personal access token |
| Repository Discovery | Fetches all repositories within an organization |
| Access Mapping | Determines which users have access to each repository |
| Aggregated Reporting | Produces a user → repository mapping |
| High Concurrency | Fetches collaborator data in parallel |
| Pagination Support | Automatically handles GitHub API pagination |
| Thread-Safe Aggregation | Uses concurrent structures to support parallel processing |
| Structured Error Handling | RFC 7807 ProblemDetail responses |
- Prerequisites
- Configuration
- Running the Project
- API Usage
- Architecture & Design Decisions
- Tech Stack
- Project Structure
Before running the project ensure you have:
- Java 21+
- Maven 3.8+
- A GitHub Personal Access Token
Required GitHub scopes:
read:org
repo
The service reads the GitHub token from an environment variable.
$env:GITHUB_TOKEN = "ghp_your_token_here"export GITHUB_TOKEN=ghp_your_token_hereThe application.yml binds this value automatically:
github:
api:
token: ${GITHUB_TOKEN:}
concurrency: 20mvn spring-boot:runmvn test# Build Docker image
docker build -t github-access-report .
# Run container
docker run -p 8080:8080 -e GITHUB_TOKEN="ghp_your_token_here" github-access-reportThe server starts on:
http://localhost:8080
Health check endpoint:
http://localhost:8080/actuator/health
This project is configured to publish automatically to GitHub Packages:
Pull and run directly from GitHub Container Registry:
docker pull ghcr.io/sonuworks/github-access-report:latest
docker run -p 8080:8080 -e GITHUB_TOKEN="ghp_your_token_here" ghcr.io/sonuworks/github-access-report:latestAdd the dependency to your pom.xml:
<dependency>
<groupId>com.sonuworks</groupId>
<artifactId>github-access</artifactId>
<version>1.0.0</version>
</dependency>Add the GitHub repository to your pom.xml or ~/.m2/settings.xml:
<repositories>
<repository>
<id>github</id>
<url>https://maven.pkg.github.com/sonuworks/github-access-report</url>
</repository>
</repositories>GET /api/access-report?org={organization}&forceRefresh={boolean}
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
org |
String | Yes | - | GitHub organization login name |
forceRefresh |
Boolean | No | false |
When true, evicts cache and fetches fresh data |
# Standard cached request (10-minute cache)
curl "http://localhost:8080/api/access-report?org=my-org"
# Force cache bypass & fresh report
curl "http://localhost:8080/api/access-report?org=my-org&forceRefresh=true"{
"organization": "my-org",
"users": [
{
"username": "alice",
"repositories": ["backend-api", "frontend-app"]
},
{
"username": "bob",
"repositories": ["backend-api"]
}
]
}All errors follow RFC 7807 ProblemDetail format.
| Scenario | HTTP Status |
|---|---|
| Organization not found | 404 |
| Invalid or missing token | 401 |
| GitHub API error | Mirrors GitHub response |
Blank org parameter |
400 |
The service uses a reactive processing pipeline built with Spring WebFlux.
fetchOrgRepositories(org)
└─ flatMap(repo -> fetchCollaborators(repo), concurrency=20)
└─ aggregator.addAccess(user, repo)
The concurrency limit of 20 parallel requests allows fast processing for large organizations while avoiding GitHub rate-limit exhaustion.
GitHub returns paginated results.
GithubApiClient.paginateFlux() automatically continues requesting pages until GitHub returns an empty response.
The per_page value is configurable in application.yml.
Default:
per_page = 100
Which is the maximum supported by GitHub.
Because collaborator requests run concurrently, aggregation must be thread-safe.
ConcurrentAggregator uses:
ConcurrentHashMap
computeIfAbsent
Collections.synchronizedList
This ensures safe writes from multiple Reactor threads.
Centralized error handling is implemented using:
GlobalExceptionHandler
It converts domain exceptions and GitHub API errors into structured ProblemDetail responses.
Special cases:
403 Forbidden404 Not Found
on collaborator endpoints are ignored to avoid failing the entire report.
| Component | Technology |
|---|---|
| Framework | Spring Boot 3.4.13 |
| Language | Java 21 |
| HTTP Client | Spring WebFlux WebClient |
| JSON | Jackson |
| Build Tool | Maven |
src/main/java/com/example/githubaccess/
├── GithubAccessApplication.java
├── config/
│ └── GithubConfig.java
├── controller/
│ └── AccessReportController.java
├── service/
│ └── AccessReportService.java
├── client/
│ ├── GithubApiClient.java
│ └── RateLimitGuard.java
├── model/
│ ├── RepositoryResponse.java
│ ├── CollaboratorResponse.java
│ ├── UserAccessReport.java
│ └── AccessReportResponse.java
├── util/
│ └── ConcurrentAggregator.java
└── exception/
├── GlobalExceptionHandler.java
├── OrganizationNotFoundException.java
└── RateLimitExceededException.java
src/main/resources/
└── application.yml
src/test/java/com/example/githubaccess/
├── GithubAccessApplicationTests.java
├── client/
│ ├── GithubApiClientTest.java
│ └── RateLimitGuardTest.java
├── controller/
│ └── AccessReportControllerTest.java
├── service/
│ └── AccessReportServiceTest.java
└── util/
└── ConcurrentAggregatorTest.java
Contributions are welcome. If you'd like to improve the project:
- Fork the repository
- Create a feature branch
- Commit your changes
- Open a pull request
This project is released under the MIT License.