GitHub Widgets

OctoStats uses the GitHub API to fetch your activity data and generate the widgets. Here's a simplified version of the process:

1. Authorization

   You sign in with GitHub to authenticate and authorize OctoStats to access your data. GitHub provides an access token to use in API calls on your behalf. Tokens are encrypted and stored in the database.

2. GitHub App Installation

   For some features, you need to install the OctoStats GitHub App to grant additional permissions - like reading private repository data to get language usage stats.

3. Data Retrieval

   OctoStats fetches your GitHub activity using the GitHub API

4. Data Processing

   The activity data is processed and transformed into the widget format

5. Widget Generation

   The widget endpoint follows this structure:

   https://octostats.mondov.dev/widget?username=<username>&type=<widget-type>&timeframe=<timeframe>&width=<width>

   Widget API Details:

   • The endpoint returns an <SVG> image that can be embedded directly
   • Width can be set to exact pixels (e.g., width=500) or percentage (e.g., width=100%)
   • User has to be registered in OctoStats
   • Timeframe is only supported for Contributions Heatmap widget type and can be 1y or 6m

6. Embed & Display

   You can embed the generated widget in your GitHub README, personal website, or anywhere HTML is supported