Github Flexi Card

Home Assistant card displaying data from Github integration

Overview

This card displays all the data provided by the GitHub integration. You can choose what data is shown and where it appears. Entity rows match the dimensions of standard rows from native cards (e.g. row height, icon/text margins, font sizes, etc.).

It works as both a standalone card (customn:github-flexi-card) and a entity row (custom:github-repo).

Note: If you only need a entity row, consider the simpler/lighter alternative by benct: github-entity-row

Breaking changes in v3.0.0

The card now uses repository names instead of entity IDs — a fundamental change to how the card is configured.

What changed

Removed	Replacement	Notes
`entities` (card config)	`repos`	List of repository names (e.g. `maxwroc/battery-state-card`) instead of entity IDs
`entity` (repo config)	`repo`	Repository name instead of entity ID
`auto` (card config)	(removed)	Auto-discovery now happens automatically when `repos` is empty
`custom:github-entity`	`custom:github-repo`	Custom element type renamed
Attribute sub-properties (e.g. `latest_release_tag`)	Direct entity keys (e.g. `latest_release`)	Entity attributes are no longer accessed via underscore notation

Migration guide

Before (v2.x):

type: 'custom:github-flexi-card'
title: My repos
entities:
  - sensor.maxwroc_battery_state_card_latest_release
  - entity: sensor.hideseek_mod_latest_release
    secondary_info: 'Released {latest_release_tag}'

After (v3.0.0):

type: 'custom:github-flexi-card'
title: My repos
repos:
  - maxwroc/battery-state-card
  - repo: maxwroc/hideseek-mod
    secondary_info: 'Released {latest_release.attributes.tag}'

If repos is omitted or empty, all GitHub repos added to Home Assistant will be auto-discovered.

Configuration

Default configuration

Please see the following file: default-config.ts

Card

Name	Type	Since	Description
title	string	v0.1.0	Card header/title text
repos	list(Repo) \| string	v3.0.0	Repos to display. Accepts a list of repository name strings (e.g. `maxwroc/battery-state-card`). When empty, all GitHub repos are auto-discovered.
sort	list(SortOptions)	v1.0.0	Sort options (order matters). Each subsequent option acts as a tiebreaker when values from the previous one are equal.

+ Repo Properties - applied to all repos

Repo

Name	Type	Default	Since	Description
repo	string	(required)	v3.0.0	Repository name e.g. `maxwroc/battery-state-card`

+ Repo Properties

Repo Properties

Name	Type	Default	Since	Description
name	KString	`"{path}"`	v0.1.0	Name override
secondary_info	KString		v0.1.0	String to display underneath the repo name
attributes	list(Attribute)		v0.1.0	Repository attributes/entities to display
url	KString \| bool		v0.2.0	URL to open on click/tap. When set to `true`, links to the repo homepage.
attribute_urls	bool		v0.2.0	When `true`, enables default URLs for all displayed attributes
attribute_color	string	`var(--primary-color)`	v2.0.0	Color applied to all attributes (icons or labels)
icon	string	`"mdi:github"`	v0.2.0	Override for repo icon
icon_color	string		v2.0.0	Icon color override
compact_view	bool	`true`	v1.0.0	When `false`, displays larger icons and values

Attribute

Name	Type	Default	Since	Description
name	string	(required)	v0.1.0	Name of the attribute (please check the list below)
icon	string		v0.1.0	Icon override (there are default icons for most of the available attributes)
url	KString \| bool		v0.2.0	URL to open on click/tap. Most attributes have default URLs, so you can simply use `true`.
label	KString		v0.5.0	Label/text which will be shown instead of the icon
color	string	`var(--primary-color)`	v2.0.0	Icon / label color

Attribute names

The GitHub integration creates multiple entities per repo. Since entity IDs can be translated, the card cannot rely on them. Instead, it automatically detects entities based on their translation_key value, which is language-agnostic. Because of this, there is a fixed list of supported repository attributes/entities you can use.

Available attribute names: forks, issues, latest_commit, latest_issue, latest_pull_request, latest_release, pull_requests, merged_pull_requests, stars, watchers, discussions, latest_discussion, latest_tag.

I recommend enabling all "Diagnostic" entities for your repo(s) on the devices page.

Sort options

Name	Type	Default	Since	Description
by	string	(required)	v1.0.0	Name of the attribute
ascending	bool	`false`	v1.0.0	Whether to sort ascending or descending

KeywordString

A KeywordString is a string that can contain special keywords — repo attribute names enclosed in curly brackets. These keywords are replaced with their corresponding attribute values at render time.

E.g. "Card version {latest_release.attributes.tag}" becomes "Card version v1.5.0"

Special repo attributes available in KeywordStrings

Name	Description
path	Repository path e.g. `maxwroc/github-flexi-card`
owner	First part of repository path e.g. `maxwroc` for the `maxwroc/github-flexi-card` repo
repo	Second part of repository path e.g. `github-flexi-card` for the `maxwroc/github-flexi-card` repo

Converting keyword value

Keywords support simple functions to convert the values

Func	Example	Description
`replace([old_string],[new_string])`	`{latest_release\|replace(Git,Proj)}`	Replaces occurrences of `old_string` with `new_string` in the value
`conditional()`	`{latest_release.attributes.tag\|conditional()}`	Renders nothing if the value doesn't exist (by default, the raw keyword is shown)
`round([number])`	`{state\|round(2)}`	Rounds the value to the specified number of decimal places

Configuration examples

Card

type: 'custom:github-flexi-card'
title: Github projects
repos:
  - repo: maxwroc/battery-state-card
    secondary_info: 'Released {latest_release}'
    url: true
    attributes:
      - name: stars
        url: true # default url to /stargazers
      - name: issues
        url: "https://my.custom.url/path"
      - name: forks
      - name: pull_requests
  - repo: maxwroc/hideseek-mod
    url: true # default url - repo homepage
    attributes:
      - stars
      - forks
  - repo: nicolo-ribaudo/tc39-proposal-url-editor-pro
    name: 'Url Editor Pro (v{latest_release})'
    secondary_info: '{latest_pull_request}'
    attributes:
      - stars
      - issues

Repo

Note: different type has to be used custom:github-repo

type: entities
title: Displayed as entity
show_header_toggle: false
entities:
  - sensor.home_assistant_v2_db
  - type: 'custom:github-repo'
    repo: maxwroc/battery-state-card
    secondary_info: 'Released {latest_release.attributes.tag}'
    url: true
    attribute_urls: true
    attributes:
      - stars
      - issues
      - forks
      - pull_requests
      - watchers
  - sensor.hassio_online
  - sensor.last_boot
  - sensor.processor_use

Card-level repo properties

Card-level repo properties let you apply the same settings to all repos at once.

type: 'custom:github-flexi-card'
title: Card-level repo properties
secondary_info: 'Released {latest_release.attributes.tag}'
url: true
attribute_urls: true
attributes:
  - stars
  - issues
  - watchers
  - forks
  - pull_requests
repos:
  - maxwroc/battery-state-card
  - maxwroc/hideseek-mod
  - nicolo-ribaudo/tc39-proposal-url-editor-pro

Labels instead of icons

type: 'custom:github-flexi-card'
title: Labels instead of icons
url: true
attribute_urls: true
attributes:
  - name: stars
    label: Stars
  - name: issues
    label: Issues
repos:
  - maxwroc/battery-state-card
  - maxwroc/hideseek-mod
  - nicolo-ribaudo/tc39-proposal-url-editor-pro

Compact view (disabling)

type: 'custom:github-flexi-card'
title: Big icons
url: true
attribute_urls: true
attributes:
  - watchers
  - stars
repos:
  - maxwroc/battery-state-card
  - repo: maxwroc/hideseek-mod
    compact_view: false
  - nicolo-ribaudo/tc39-proposal-url-editor-pro

Sorting

type: 'custom:github-flexi-card'
title: Sort by stars and forks (asc)
secondary_info: '{latest_release}'
url: true
attribute_urls: true
attributes:
  - watchers
  - stars
  - issues
  - forks
sort:
  - by: stars
  - by: forks
    ascending: true
repos:
  - maxwroc/battery-state-card
  - maxwroc/hideseek-mod
  - maxwroc/github-flexi-card
  - nicolo-ribaudo/tc39-proposal-url-editor-pro
  - repo: maxwroc/homeassistant
    secondary_info: null

How to install?

Install via HACS — look for the card in the Frontend plugins collection.

If you use YAML mode, remember to add a resource entry for the JS bundle in ui-lovelace.yaml:

resources:
  - url: /hacsfiles/github-flexi-card/github-flexi-card.js
    type: module

Automation

If you want to receive notifications whenever something changes with the repo you can use my automation as an example: https://github.com/maxwroc/homeassistant/blob/master/configuration/packages/github.yaml

Development

Card created based on lovelace-card-boilerplate

npm install
npm run build

For new features create your branch based on vNext and for fixes based on master.

Troubleshooting

If the card isn't rendering as expected or you want to inspect the data it receives from Home Assistant, enable the debug option.

Using the debug config

Add debug to your card or repo configuration. When enabled, the repo view is replaced with a diagnostic panel showing the resolved config, entity map, and all entity states.

Value	Effect
`true`	Shows debug output for all repos
`"owner/repo-name"`	Shows debug output only for the matching repo

The debug panel includes a Show / hide toggle and a Copy to clipboard button so you can easily share the data when reporting issues.

Card-level (all repos)

type: 'custom:github-flexi-card'
debug: true
repos:
  - maxwroc/battery-state-card
  - maxwroc/hideseek-mod

Single repo

type: 'custom:github-flexi-card'
repos:
  - repo: maxwroc/battery-state-card
    debug: true
  - maxwroc/hideseek-mod

Specific repo by name (card-level)

type: 'custom:github-flexi-card'
debug: "maxwroc/battery-state-card"
repos:
  - maxwroc/battery-state-card
  - maxwroc/hideseek-mod

Do you like the card?

Don't "buy me a coffee" — just star it on GitHub! That's enough to let me know you like it and will definitely motivate me to keep working on it and other cards.

My other HA related repos

battery-state-card | homeassistant-config | lovelace-card-boilerplate

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
.github		.github
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
hacs.json		hacs.json
package-lock.json		package-lock.json
package.json		package.json
rollup.config.js		rollup.config.js
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Github Flexi Card

Overview

Breaking changes in v3.0.0

What changed

Migration guide

Configuration

Default configuration

Card

Repo

Repo Properties

Attribute

Attribute names

Sort options

KeywordString

Converting keyword value

Configuration examples

Card

Repo

Card-level repo properties

Labels instead of icons

Compact view (disabling)

Sorting

How to install?

Automation

Development

Troubleshooting

Using the debug config

Card-level (all repos)

Single repo

Specific repo by name (card-level)

Do you like the card?

My other HA related repos

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages