{"id":7260,"library":"gidgethub","title":"Gidgethub","description":"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.","status":"active","version":"5.4.0","language":"en","source_language":"en","source_url":"https://github.com/brettcannon/gidgethub","tags":["github","async","api","webhooks","sans-io","aiohttp","httpx"],"install":[{"cmd":"pip install gidgethub","lang":"bash","label":"Base installation"},{"cmd":"pip install gidgethub[aiohttp]","lang":"bash","label":"With aiohttp support"},{"cmd":"pip install gidgethub[httpx]","lang":"bash","label":"With httpx support"}],"dependencies":[{"reason":"Required for GitHub App authentication (JWTs). Minimum version 2.4.0 since gidgethub v5.2.0.","package":"PyJWT","optional":false},{"reason":"A popular asynchronous HTTP client library, commonly used with gidgethub via gidgethub.aiohttp.","package":"aiohttp","optional":true},{"reason":"Another asynchronous HTTP client library, supported via gidgethub.httpx.","package":"httpx","optional":true},{"reason":"Asynchronous HTTP client support via gidgethub.tornado.","package":"tornado","optional":true}],"imports":[{"note":"Commonly used with aiohttp for the I/O layer.","symbol":"GitHubAPI","correct":"from gidgethub.aiohttp import GitHubAPI"},{"note":"Used for routing GitHub webhook events to specific handlers.","symbol":"Router","correct":"from gidgethub import routing"},{"note":"Represents a GitHub webhook event in a sans-I/O fashion.","symbol":"Event","correct":"from gidgethub.sansio import Event"}],"quickstart":{"code":"import asyncio\nimport os\nimport aiohttp\nfrom gidgethub.aiohttp import GitHubAPI\n\nasync def get_user_info():\n    # Replace 'YOUR_GH_USERNAME' with your GitHub username\n    # Ensure GH_AUTH environment variable is set with a GitHub Personal Access Token\n    # (e.g., export GH_AUTH='ghp_YOURTOKENHERE')\n    username = 'YOUR_GH_USERNAME'\n    oauth_token = os.environ.get('GH_AUTH', '')\n\n    if not oauth_token:\n        print(\"Error: GH_AUTH environment variable not set. Please set your GitHub Personal Access Token.\")\n        return\n\n    async with aiohttp.ClientSession() as session:\n        gh = GitHubAPI(session, username, oauth_token=oauth_token)\n        try:\n            # Fetch details for the authenticated user\n            user_data = await gh.getitem(f'/users/{username}')\n            print(f\"User Login: {user_data['login']}\")\n            print(f\"User Name: {user_data.get('name', 'N/A')}\")\n            print(f\"Public Repos: {user_data['public_repos']}\")\n            print(f\"Followers: {user_data['followers']}\")\n        except Exception as e:\n            print(f\"An error occurred: {e}\")\n\nif __name__ == '__main__':\n    # For Python 3.7+\n    asyncio.run(get_user_info())\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.8 or a later supported version.","message":"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.","severity":"breaking","affected_versions":"<5.4.0"},{"fix":"Remove any manual inclusion of `machine-man-preview` headers when obtaining installation access tokens; `gidgethub` will handle this automatically.","message":"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.","severity":"breaking","affected_versions":">=5.0.1"},{"fix":"Implement explicit error handling for `gidgethub.RateLimitExceeded` exceptions and incorporate your own rate-limiting or retry logic if necessary.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Configure your GitHub webhooks to use HMAC SHA256 for payload signatures. `gidgethub`'s webhook validation will automatically prefer this.","message":"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.","severity":"gotcha","affected_versions":">=5.1.0"},{"fix":"Design your webhook handlers to be independent of execution order. If sequential processing is critical, manage it within a single, composite callback function.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","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.","error":"gidgethub.BadRequest: Resource not accessible by integration"},{"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.","cause":"The GitHub Personal Access Token or App JWT provided is invalid, expired, or malformed.","error":"gidgethub.BadRequest: Bad credentials"},{"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.","cause":"Your application has made too many requests to the GitHub API within a short period, exceeding the rate limit imposed by GitHub.","error":"gidgethub.exceptions.RateLimitExceeded: rate limit exceeded"}]}