djangocms-gh-stats 2026.7.1

A django CMS plugin to display GitHub statistics for organisations and repositories.

A django CMS plugin package that fetches statistics from the GitHub REST API and displays them on your CMS-powered website.

Features

The package ships the following CMS plugins, all configurable to target either a GitHub organisation or a specific repository:

• GitHub Stars — display the star count of a repository.

• GitHub Forks — display the fork count of a repository.

• GitHub Open Issues — display the open issue count of a repository.

• GitHub Contributors — display an avatar grid of top contributors.

Installation

Install using uv (recommended):

uv add djangocms-gh-stats

Or using pip:

pip install djangocms-gh-stats

Configuration

Add the application to INSTALLED_APPS in your Django settings:

INSTALLED_APPS = [
    ...
    "djangocms_gh_stats",
    ...
]

Run the database migrations:

python manage.py migrate djangocms_gh_stats

Optional settings

DJANGOCMS_GH_STATS_TOKEN

A GitHub Personal Access Token (PAT) for authenticated API requests. Unauthenticated requests are subject to GitHub’s lower rate limit of 60 requests per hour per IP address. Providing a token raises this limit to 5,000 requests per hour:

DJANGOCMS_GH_STATS_TOKEN = "github_pat_..."

DJANGOCMS_GH_STATS_CACHE_TIMEOUT

How long (in seconds) to cache API responses. Defaults to 600 (10 minutes). Set to 0 to disable caching:

DJANGOCMS_GH_STATS_CACHE_TIMEOUT = 600

Usage

After installation, the following plugins are available in the django CMS plugin picker under the GitHub Stats module:

• GitHub Stars

• GitHub Forks

• GitHub Open Issues

• GitHub Contributors

Each plugin has the following configuration fields:

• Scope — choose between Organisation or Repository.

• Organisation — the GitHub organisation or user name (e.g. django-cms).

• Repository — the repository name (required when scope is Repository).

Development

This project is managed with uv.

Clone the repository and install dependencies:

git clone https://github.com/marksweb/djangocms_gh_stats.git
cd djangocms_gh_stats
uv sync

Run the tests:

uv run pytest

Run the linter:

uv run ruff check djangocms_gh_stats/ tests/

Releasing

Releases are created with the Release and Publish GitHub Actions workflow.

The workflow uses CalVer tags in YYYY.M.D format and can append .N for multiple releases on the same day.

To create a release:

1. Run the workflow from the Actions tab.

2. Optionally provide a CalVer version (for example 2026.6.28).

3. The workflow creates the Git tag, creates a GitHub release, builds with uv, and publishes to PyPI via trusted publishing.

4. The workflow updates djangocms_gh_stats/__init__.py and inserts a new <version> (<YYYY-MM-DD>) section directly below the top changelog section, preserving the unreleased heading.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the BSD 3-Clause License — see the LICENSE file for details.