ghstatus

0.3.2 verified Sat May 09 auth: no python maintenance

A lightweight Python library and CLI tool to update GitHub commit statuses via the Checks API. Supports setting commit statuses (pending, success, failure, error) with context, description, and target URL. Current version: 0.3.2. Release cadence: infrequent, last release in 2021.

pip install ghstatus

Common errors

error ModuleNotFoundError: No module named 'ghstatus' ↓

cause ghstatus is not installed, or installed in a different environment.

fix

Run 'pip install ghstatus' in the correct virtual environment.

error AttributeError: module 'ghstatus' has no attribute 'Session' ↓

cause You might have a conflicting file named 'ghstatus.py' in your project shadowing the package.

fix

Rename your local file. The correct import is 'import ghstatus' and then use 'ghstatus.Session(token)'.

error ghstatus.exceptions.GitHubError: 401 Unauthorized ↓

cause Invalid or expired GitHub personal access token, or token lacks 'repo:status' permission.

fix

Generate a new token at https://github.com/settings/tokens with 'repo:status' scope.

error ghstatus.exceptions.GitHubError: 422 Unprocessable Entity ↓

cause Invalid 'state' parameter (must be one of error, failure, pending, success) or incorrect owner/repo format.

fix

Check state is exactly one of the allowed values. Ensure owner/repo is in 'username/repository' format.

error TypeError: __init__() takes 1 positional argument but 2 were given ↓

cause Trying to pass a username and password to Session in a version where only token is accepted.

fix

Use only a token: Session(token). For older usage, downgrade to ghstatus 0.1.x.

Warnings

gotcha The library only supports GitHub API v3. It does not use the newer Checks API endpoint for creating checks (e.g., check runs). If you need check runs, use PyGithub or requests directly. ↓

fix Use PyGithub or the requests library with the Checks API endpoints.

deprecated The 'Session' constructor expects a single argument (token). In older versions, you could pass a password; this is now removed. ↓

fix Use Session(token) only.

gotcha The 'set' method does not validate the 'state' parameter. Passing an invalid state (e.g., 'queued') will cause a 422 error from GitHub. ↓

fix Ensure state is one of 'error', 'failure', 'pending', or 'success'.

gotcha The library sets status using the '/repos/:owner/:repo/statuses/:sha' endpoint, which is for commit statuses (not check runs). It does not support 'details_url'. This means you cannot attach rich Markdown output. ↓

fix For check runs, use a different library or raw API calls.

breaking Python 2 support was removed in version 0.3.0. Only Python 3 is supported. ↓

fix Use Python 3.6+.

Imports

ghstatus
```
import ghstatus
```
Often confused with 'import gh_status' or 'from ghstatus import ghstatus'.

Quickstart

Updates a GitHub commit status. Requires a personal access token with repo status permissions.

import os
import ghstatus

# Use a GitHub personal access token
token = os.environ.get('GITHUB_TOKEN', '')
s = ghstatus.Session(token)
s.set('owner/repo', 'commit_sha', 'success', 'CI passed', 'https://ci.example.com/123')
print('Status updated.')