GitHub Cloud Connector

A robust, production-ready Python connector built with FastAPI that provides a simplified interface for interacting with GitHub's REST API. It handles authentication, data validation, and error management out-of-the-box.

Features

• Asynchronous Operations: Uses async/await and httpx for high-performance non-blocking API calls.
• Repository Management: Fetch details and list repositories by user.
• Issue Interaction: List issues with filters and create new issues programmatically.
• Commit History: Retrieve detailed commit records from specific repositories.
• Integrated Health Checks: Automatically verifies GitHub token status.
• Standardized Error Handling: Custom global exception handlers for API states (401, 403, 404, etc.).

Prerequisites

• Python 3.10 or higher
• A GitHub Personal Access Token (PAT)
  • Required Scopes: repo (Full control of private repositories) and read:user (Read user profile data).

Getting Started

1. Setup Environment

Clone the repository and navigate to the project directory:

cd github-connector
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Configure Environment Variables

Create a .env file in the project root:

cp .env.example .env

Edit the .env file with your GitHub token:

• GITHUB_TOKEN: Your Personal Access Token.
• GITHUB_BASE_URL: Defaults to https://api.github.com.

3. Run the Application

Start the FastAPI server using uvicorn:

uvicorn app.main:app --reload

The service will be available at http://127.0.0.1:8000.

---

API Documentation

Documentation & Health

Method	Endpoint	Description
GET	/	Root entry point with basic info
GET	/docs	Interactive Swagger UI
GET	/health	Health check verifying the GitHub PAT

Repositories

Method	Endpoint	Parameters	Example Command
GET	/repos/{username}	username	curl -X GET "http://127.0.0.1:8000/repos/octocat"
GET	/repos/{owner}/{repo}	owner, repo	curl -X GET "http://127.0.0.1:8000/repos/openai/whisper"

Issues

Method	Endpoint	Parameters	Example Command
GET	/repos/{owner}/{repo}/issues	owner, repo, state, page	curl -X GET "http://127.0.0.1:8000/repos/fastapi/fastapi/issues?state=open"
POST	/repos/{owner}/{repo}/issues	owner, repo + JSON Body	curl -X POST "http://127.0.0.1:8000/repos/octocat/hello-world/issues" -H "Content-Type: application/json" -d '{"title": "Bug", "body": "Need fix", "labels": ["bug"]}'

Commits

Method	Endpoint	Parameters	Example Command
GET	/repos/{owner}/{repo}/commits	owner, repo, sha, page	curl -X GET "http://127.0.0.1:8000/repos/python/cpython/commits?per_page=5"

---

Error Handling

The application maps GitHub API errors to semantic HTTP responses:

• 401 Unauthorized: Occurs when the GITHUB_TOKEN is invalid or missing.
• 403 Forbidden: Triggered by GitHub rate limiting or insufficient token permissions.
• 404 Not Found: Returned when the requested repository, user, or issue does not exist.
• 500 Internal Server Error: Global fallback for unexpected API failures.

Project Structure

github-connector/
├── app/
│   ├── main.py              # Application entry point & configuration
│   ├── config.py            # Settings management (pydantic-settings)
│   ├── routers/             # API route definitions
│   │   ├── repos.py         # Repository endpoints
│   │   ├── issues.py        # Issue endpoints
│   │   └── commits.py       # Commit endpoints
│   ├── services/            # Core business logic
│   │   └── github_service.py# HTTPX GitHub API client
│   ├── models/              # Pydantic schemas for request/response validation
│   │   └── schemas.py
│   └── utils/               # Shared utilities
│       └── exceptions.py    # Custom error handlers
├── .env.example
├── .gitignore
├── requirements.txt
└── README.md

Example Response (Issue Retrieval)

[
  {
    "id": 123456,
    "number": 42,
    "title": "Fix memory leak in connector",
    "body": "Detailed description of the issue...",
    "state": "open",
    "html_url": "https://github.com/owner/repo/issues/42",
    "user": { "login": "developer_jane", "id": 789... },
    "created_at": "2024-04-12T10:00:00Z"
  }
]