The idea is to allow for Kanban boards to be stored in Git. This means that a Git ref will store all the cards, lanes, milestones, and other metadata associated with a board. Then using a git commit chain as the "changelog" we can perform actions on the board by editing files and committing them.

Ideally the layout will be conducive to allowing for offline updates to then be easily merged into the shared instance at a later point.

First class objects and their properties


Cards are individual items in the Kanban. They are meant to represent chunks of work to be done, but could equally represent bugs or other things.

A card has a UUID, of the form cards/XXXXXXX

They have a number of required properties:

They may have the following properties also


Lanes are groupings of cards. They have a few properties of their own and otherwise are entirely defined by the set of cards within them. Each card indicates which lane it is in, and this is considered the canonical source of that information.

A lane has a UUID, of the form lanes/XXXXXXXX

They have a number of required properties:

They have optional properties including:

Lanes also contain an ordered list of the UUIDs of all the cards in them.


Milestones are an optional grouping of cards, typically representing a deadline or feature goal.

A milestone has a UUID, of the form milestones/XXXXXXXX

Milestones have a number of required properties:

They have optional properties including:

Notes related to those objects

Normalising lane contents

When a card is put into a lane (by setting its lane property) the lane doesn't necessarily know about it. During normalisation of the board, the lane's list of cards is updated. Cards which no longer claim to be part of the lane are removed from the lane and cards which newly claim to be part of the lane are added at the bottom of the lane in asciibetical-by-UUID order.

Operations which users perform on a board

Lane related operations

Milestone related operations

Card related operations

Storing the kanban in a Git tree

Given the UUIDs are of the form type/XXXXXXXX they easily fit into the idea of a filesystem tree. The UUIDs will be short, likely something easily remembered, so whatever tool manipulates the kanban will choose sensible ones.

As such, each object will be a simple text file in a file in a tree of the form implied by the UUIDs. The format of the text file will be RFC822 style key-value pairs, with keys ordered asciibetically.