Gidgethub

5.4.0 · active · verified Thu Apr 16

Gidgethub is an asynchronous Python library for interacting with the GitHub API. It employs a sans-I/O approach, allowing users to integrate it with their preferred HTTP client library. The current version is 5.4.0 and it maintains an active release cadence, providing ongoing support and new features.

Common errors

```
gidgethub.BadRequest: Resource not accessible by integration
```
cause This error typically indicates that the GitHub App or Personal Access Token used for authentication does not have the necessary permissions (scopes) to access the requested resource or perform the action.

fix Review the required permissions for the GitHub API endpoint you are calling. Adjust your GitHub App's permissions or regenerate your Personal Access Token with the correct scopes (e.g., 'repo' scope for repository actions).
```
gidgethub.BadRequest: Bad credentials
```
cause The GitHub Personal Access Token or App JWT provided is invalid, expired, or malformed.

fix Verify that your `GH_AUTH` environment variable (or equivalent) contains a valid and unexpired GitHub Personal Access Token. If using a GitHub App, ensure the JWT is correctly generated and signed. Regenerate the token/JWT if unsure.
```
gidgethub.exceptions.RateLimitExceeded: rate limit exceeded
```
cause Your application has made too many requests to the GitHub API within a short period, exceeding the rate limit imposed by GitHub.

fix Implement retry logic with exponential backoff, check the `x-ratelimit-*` headers in responses, and wait until the `x-ratelimit-reset` time before making further requests. Avoid unnecessary API calls.

Warnings

breaking Gidgethub no longer supports Python 3.6 or 3.7. Users on these End-of-Life Python versions must upgrade to Python 3.8 or newer.
Fix: Upgrade your Python environment to 3.8 or a later supported version.
breaking The `machine-man-preview` header, previously used for GitHub App installation access tokens, was removed in `gidgethub` v5.0.1 as it is no longer required by GitHub's API.
Fix: Remove any manual inclusion of `machine-man-preview` headers when obtaining installation access tokens; `gidgethub` will handle this automatically.
gotcha Since v2.0, `gidgethub` no longer automatically sleeps when nearing the GitHub API rate limit. Instead, a `RateLimitExceeded` exception is raised when the rate limit is hit.
Fix: Implement explicit error handling for `gidgethub.RateLimitExceeded` exceptions and incorporate your own rate-limiting or retry logic if necessary.
gotcha For webhook validation, `gidgethub` v5.1.0 and later utilize the `X-Hub-Signature-256` header when available for enhanced security. Ensure your GitHub webhook configuration uses SHA256.
Fix: Configure your GitHub webhooks to use HMAC SHA256 for payload signatures. `gidgethub`'s webhook validation will automatically prefer this.
gotcha The execution order of callbacks registered with `gidgethub.routing.Router` became non-deterministic starting from v5.0.0. Do not rely on registration order for callback execution.
Fix: Design your webhook handlers to be independent of execution order. If sequential processing is critical, manage it within a single, composite callback function.

Install

pip install gidgethub Base installation
pip install gidgethub[aiohttp] With aiohttp support
pip install gidgethub[httpx] With httpx support

Imports

GitHubAPI
```
from gidgethub.aiohttp import GitHubAPI
```
Commonly used with aiohttp for the I/O layer.
Router
```
from gidgethub import routing
```
Used for routing GitHub webhook events to specific handlers.
Event
```
from gidgethub.sansio import Event
```
Represents a GitHub webhook event in a sans-I/O fashion.

Quickstart

This quickstart demonstrates how to make a simple API call to fetch user information using `gidgethub` with `aiohttp`. It requires a GitHub Personal Access Token set in the `GH_AUTH` environment variable for authentication.

import asyncio
import os
import aiohttp
from gidgethub.aiohttp import GitHubAPI

async def get_user_info():
    # Replace 'YOUR_GH_USERNAME' with your GitHub username
    # Ensure GH_AUTH environment variable is set with a GitHub Personal Access Token
    # (e.g., export GH_AUTH='ghp_YOURTOKENHERE')
    username = 'YOUR_GH_USERNAME'
    oauth_token = os.environ.get('GH_AUTH', '')

    if not oauth_token:
        print("Error: GH_AUTH environment variable not set. Please set your GitHub Personal Access Token.")
        return

    async with aiohttp.ClientSession() as session:
        gh = GitHubAPI(session, username, oauth_token=oauth_token)
        try:
            # Fetch details for the authenticated user
            user_data = await gh.getitem(f'/users/{username}')
            print(f"User Login: {user_data['login']}")
            print(f"User Name: {user_data.get('name', 'N/A')}")
            print(f"Public Repos: {user_data['public_repos']}")
            print(f"Followers: {user_data['followers']}")
        except Exception as e:
            print(f"An error occurred: {e}")

if __name__ == '__main__':
    # For Python 3.7+
    asyncio.run(get_user_info())

view raw JSON →