GitHub Repository Activity Connector

A scalable and maintainable Java connector for fetching GitHub repository activity data. This connector authenticates using a personal access token and retrieves a list of public repositories for a given GitHub user or organization, along with the most recent commits for each repository.

Features

• ✅ Authentication: Uses GitHub Personal Access Token for API access
• ✅ Repository Fetching: Retrieves all public repositories for a user/organization
• ✅ Commit History: Fetches the last 20 commits per repository (configurable)
• ✅ Pagination Support: Handles API pagination automatically
• ✅ Rate Limiting: Built-in rate limit handling and retry logic
• ✅ Error Handling: Graceful error handling with specific exception types
• ✅ CLI Interface: Command-line interface for easy usage
• ✅ Structured Output: Returns data as structured Java POJOs
• ✅ Logging: Comprehensive logging with configurable levels
• ✅ Configurable: Flexible configuration options

Prerequisites

• Java 11 or higher
• Maven 3.6 or higher
• GitHub Personal Access Token

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd github-activity-connector

2. Build the Project

mvn clean compile

3. Run Tests

mvn test

4. Create Executable JAR

mvn package

This will create a github-activity-connector-1.0.0.jar file in the target/ directory.

5. Create GitHub Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens
2. Click "Generate new token"
3. Select the following scopes:
   • public_repo (for accessing public repositories)
   • read:user (for accessing user information)
4. Copy the generated token

Usage

Command Line Interface

The connector provides a command-line interface for easy usage:

java -jar target/github-activity-connector-1.0.0.jar [OPTIONS] <username>

Basic Usage

# Fetch activity for a specific user
java -jar target/github-activity-connector-1.0.0.jar -t YOUR_GITHUB_TOKEN octocat

# Fetch activity for an organization
java -jar target/github-activity-connector-1.0.0.jar -t YOUR_GITHUB_TOKEN microsoft

Command Line Options

Option	Description	Default
-t, --token	GitHub Personal Access Token (required)	-
-c, --commits	Maximum commits per repository	20
-v, --verbose	Enable verbose output	false
-s, --summary	Show only summary information	false
-f, --format	Output format (table, json, csv)	table
-h, --help	Show help message	-

Examples

# Verbose output with custom commit count
java -jar target/github-activity-connector-1.0.0.jar -t YOUR_TOKEN -v -c 10 octocat

# Summary only
java -jar target/github-activity-connector-1.0.0.jar -t YOUR_TOKEN -s octocat

# Using environment variable for token
export GITHUB_TOKEN="your_token_here"
java -jar target/github-activity-connector-1.0.0.jar -t $GITHUB_TOKEN octocat

Programmatic Usage

You can also use the connector programmatically in your Java applications:

import com.savantlabs.github.config.GitHubConfig;
import com.savantlabs.github.service.GitHubActivityConnector;
import com.savantlabs.github.model.Repository;
import com.savantlabs.github.model.Commit;

public class Example {
    public static void main(String[] args) {
        // Create configuration
        GitHubConfig config = new GitHubConfig("your_github_token");
        
        // Create connector
        GitHubActivityConnector connector = new GitHubActivityConnector(config);
        
        try {
            // Fetch repositories and commits
            List<Repository> repositories = connector.fetchRepositoryActivity("octocat");
            
            // Process results
            for (Repository repo : repositories) {
                System.out.println("Repository: " + repo.getFullName());
                System.out.println("Description: " + repo.getDescription());
                System.out.println("Language: " + repo.getLanguage());
                System.out.println("Stars: " + repo.getStargazersCount());
                
                List<Commit> commits = repo.getCommits();
                System.out.println("Recent commits: " + commits.size());
                
                for (Commit commit : commits) {
                    System.out.println("  - " + commit.getSha().substring(0, 7) + 
                                     " by " + commit.getCommitAuthorName() + 
                                     ": " + commit.getMessage());
                }
            }
            
        } catch (GitHubConnectorException e) {
            System.err.println("Error: " + e.getMessage());
        } finally {
            connector.close();
        }
    }
}

Configuration

The connector supports various configuration options:

GitHubConfig config = new GitHubConfig(
    "your_token",           // GitHub token
    30,                     // Page size for API requests
    20,                     // Max commits per repository
    30,                     // Timeout in seconds
    3,                      // Max retries
    1000                    // Retry delay in milliseconds
);

Data Models

The connector returns structured Java objects (POJOs):

Repository

• id: Repository ID
• name: Repository name
• fullName: Full repository name (owner/repo)
• description: Repository description
• language: Primary programming language
• stargazersCount: Number of stars
• forksCount: Number of forks
• createdAt: Creation timestamp
• updatedAt: Last update timestamp
• commits: List of recent commits

Commit

• sha: Commit SHA hash
• message: Commit message
• author: Commit author information
• date: Commit timestamp
• htmlUrl: GitHub URL for the commit

Error Handling

The connector provides specific exception types for different error scenarios:

• GitHubConnectorException: Base exception for all connector errors
• GitHubAuthenticationException: Authentication-related errors
• GitHubRateLimitException: Rate limit exceeded errors

Rate Limiting

The connector automatically handles GitHub's rate limiting:

• Authenticated requests: 5,000 requests per hour
• Built-in buffer: Stops before hitting exact limit
• Automatic waiting: Waits for rate limit reset when needed
• Retry logic: Automatic retries with exponential backoff

Logging

The connector uses SLF4J with Logback for logging:

• Console output: INFO level and above
• File output: Detailed logs in logs/github-activity-connector.log
• Configurable: Modify src/main/resources/logback.xml for custom logging

Architecture

The connector follows a clean, scalable architecture:

├── model/              # POJOs for data representation
├── config/             # Configuration classes
├── client/             # GitHub API client
├── service/            # Main connector service
├── exception/          # Custom exception classes
└── cli/                # Command-line interface

Key Design Principles

1. Separation of Concerns: Each component has a single responsibility
2. Scalability: Designed to handle large numbers of repositories
3. Maintainability: Clean code with comprehensive documentation
4. Error Resilience: Graceful handling of failures
5. Testability: Loosely coupled components for easy testing

Performance Considerations

• Pagination: Efficiently handles large result sets
• Rate Limiting: Respects GitHub's API limits
• Connection Pooling: Reuses HTTP connections for efficiency
• Memory Management: Streams data to avoid memory issues
• Concurrent Safety: Thread-safe implementation

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the existing GitHub Issues
2. Create a new issue with detailed information
3. Include logs and error messages when reporting bugs

Changelog

v1.0.0

• Initial release
• GitHub repository and commit fetching
• CLI interface
• Rate limiting and error handling
• Comprehensive logging
• Structured data models