Display your GitHub contribution activity on an AWTRIX NG clock through Home Assistant.
The integration fetches your contribution history, renders a compact 365-day heatmap for the AWTRIX NG 32×8 display, and publishes it over MQTT.
- 📊 365-day GitHub contribution heatmap
- 🖥️ Multiple AWTRIX NG clocks
- 👤 GitHub avatar display
- 🔄 Configurable refresh interval
- 💾 Avatar caching
- 📡 Per-clock MQTT handling
- ⚡ Automatic recovery when a clock comes back online
- 🚫 Automatic app cleanup when disabled or a clock is removed
- 🔄 Manual refresh service
- 📈 Home Assistant status information
- 👥 Multiple GitHub accounts through separate integration entries
If the repository is not yet available in the HACS default repository list, add it as a custom repository:
- Open HACS → Integrations
- Open the ⋮ menu
- Select Custom repositories
- Add
https://github.com/OsamaShabrez/ha-awtrix-github-heatmap - Select Integration
- Install AWTRIX NG GitHub Heatmap
Then add GitHub Heatmap from:
Settings → Devices & services → Add integration
| Option | Description |
|---|---|
| GitHub username | GitHub account to display |
| AWTRIX clocks | One or more AWTRIX NG clocks |
| Refresh interval | Contribution refresh interval |
| Enabled | Enable or disable the heatmap |
| AWTRIX icon ID | Optional icon ID already uploaded to the selected clocks |
Each integration entry represents one GitHub account. Multiple accounts can be configured using separate entries.
The heatmap is rendered for the AWTRIX NG 32×8 matrix.
By default, the GitHub avatar is displayed alongside the contribution calendar.
You can optionally specify an AWTRIX icon ID in the integration configuration.
The icon must be uploaded to the AWTRIX NG clock by the user before configuring the integration. This integration does not upload or manage icons on the clock.
If an icon ID is configured:
- The configured AWTRIX icon is displayed instead of the GitHub avatar.
- The GitHub avatar is not downloaded.
- The heatmap keeps the same 8×8 icon area and separator.
- The icon must already exist on every selected AWTRIX clock.
- The same icon ID is used for all selected clocks.
If the icon ID is left empty, the GitHub avatar is used instead.
The integration is designed to handle temporary connectivity problems without unnecessarily clearing the display.
- GitHub API failures retain the last valid data.
- MQTT failures are handled independently per clock.
- Offline clocks are updated automatically when they return.
- Adding a clock publishes the current heatmap.
- Removing a clock removes the app from that clock.
- Disabling the integration removes the app from the selected clocks.
No separate Home Assistant automation is required for cleanup.
The integration provides the github_heatmap.refresh action:
action: github_heatmap.refreshThis immediately refreshes the contribution data and republishes the heatmap to the selected clocks.
Contribution data is provided by the GitHub Contributions API.
The integration uses the upstream API's last-year contribution dataset.
When reporting an issue, include:
- Home Assistant version
- GitHub Heatmap version
- AWTRIX NG firmware version
- Number of configured clocks
- Relevant Home Assistant or MQTT logs
Remove credentials, tokens, passwords, and other sensitive information before posting logs.
This project was inspired by and uses the GitHub Contributions API created by grubersjoe.
Licensed under the MIT License. See LICENSE.
