No description
  • Go 98.2%
  • Dockerfile 1.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jonathan Warykowski 15367a733c
All checks were successful
CI / checks (push) Successful in 59s
CI / go (push) Successful in 0s
ci: Go checks from the shared workflow (#7)
Reviewed-on: #7
2026-11-04 04:56:49 +00:00
.github/workflows ci: Go checks from the shared workflow (#7) 2026-11-04 04:56:49 +00:00
build feat: each build comes with its complete GPL source (#5) 2026-11-01 02:17:20 +00:00
cmd/builder feat: each build comes with its complete GPL source (#5) 2026-11-01 02:17:20 +00:00
container feat: each build comes with its complete GPL source (#5) 2026-11-01 02:17:20 +00:00
keymap feat: the builder: layout JSON in, firmware and its source out (#1) 2026-10-31 13:58:34 +00:00
qmk feat: the builder: layout JSON in, firmware and its source out (#1) 2026-10-31 13:58:34 +00:00
.dockerignore feat: the builder: layout JSON in, firmware and its source out (#1) 2026-10-31 13:58:34 +00:00
.gitignore feat: the layout model and firmware generator, from keybars-pro 2026-10-31 17:26:27 +11:00
.golangci.yml feat: the layout model and firmware generator, from keybars-pro 2026-10-31 17:26:27 +11:00
CLAUDE.md feat: each build comes with its complete GPL source (#5) 2026-11-01 02:17:20 +00:00
go.mod feat: the layout model and firmware generator, from keybars-pro 2026-10-31 17:26:27 +11:00
LICENSE chore: MIT licence, before the repo goes public (#4) 2026-10-31 23:00:07 +00:00
README.md docs: release process for tags and the builder image (#6) 2026-11-01 04:37:00 +00:00
RELEASING.md docs: release process for tags and the builder image (#6) 2026-11-01 04:37:00 +00:00

keybars-build

Builds keybars Pro's layouts into QMK firmware, for action keys. keybars Pro's Layout page edits a keyboard's layout; this repository is everything that turns one into firmware with the keybars module in it, and the service that builds it for the app.

  • qmk: keyboards from QMK's data (matrix, physical layouts, LEDs, bootloader) and the keycode catalogue, downloaded from QMK's API and kept, with a parser for what a keymap entry does.
  • keymap: the layout format (QMK's keymap.json plus layer names and colours, combos, tap-hold settings and keys an action may never take), its checks, import from Oryx, QMK and Vial, and Layout.Firmware, which writes the keymap folder QMK builds.

keybars Pro imports both, so the app checks a layout with the same code the builder builds it with.

k, _ := qmk.Fetcher{}.Keyboard(ctx, "zsa/voyager")
c, _ := qmk.Fetcher{}.Catalogue(ctx)
l, report, _ := keymap.Import("layout.zip", zipped, k, c)
files, _ := l.Firmware(k, c) // keymap.c, config.h, rules.mk, keymap.json

Only keycodes the catalogue formats reach the generated C, never the layout's own text, so a layout can't carry code: the builder takes layout JSON from anyone with a keybars Pro licence and builds it with no network.

  • build and cmd/builder: layout JSON in, firmware and a zip of its source out. builder serve answers keybars.app's Worker (POST /build, GET /health, GET /source/<archive>); builder build layout.json builds one here.
  • container/: the image the builder runs in on Cloudflare Containers.

Oryx layouts (any with ZSA's modules) build on ZSA's fork (github.com/zsa/qmk_firmware, branch firmware25), which names the Moonlander zsa/moonlander/reva or revb; the builder builds both unless asked for one. Other layouts build on QMK master.

The image

podman build -f container/Dockerfile -t keybars-builder .
podman run --rm --network none -v "$PWD":/work:Z --userns=keep-id \
  keybars-builder build -o /work/out /work/layout.json

QMK master and ZSA's fork are pinned by commit and the keybars module by tag (build args QMK_COMMIT, ZSA_COMMIT, KEYBARS_QMK_REF), and QMK's API is generated into the image, so builds need no network. API_FILTER=zsa generates only ZSA's keyboards, for a quicker local image. To build with a local copy of the module: --build-context module=../keybars-qmk.

The Worker in front (licence check, jobs, firmware in R2) is a route on keybars.app, in keybars-www.

The GPL

Firmware is QMK firmware, GPL-2.0-or-later, and keybars Pro is sold, so each build comes with its complete source, not a link to someone else's. The image keeps an archive of each tree as built (QMK with its submodules and the keybars module: /source/qmk-<commit>.tar.gz, zsa-<commit>.tar.gz). Publishing an image copies its archives to R2, and keybars.app serves them from there as https://keybars.app/action-keys/source/<archive> (R2 has no download charge; a container does). The builder's own GET /source/ is for checking a running container. Each build's source zip holds its keymap folder and a BUILDING.md that links its archive and makes the GPL's three-year written offer ([email protected]). Keep every archive a build has linked downloadable for three years after it, including after the pins move.

Develop

RELEASING.md has how a version gets from a tag to keybars.app.

go test ./... and golangci-lint run ./.... Tests need no network: QMK's documents are in qmk/testdata.

Licence

MIT, see LICENSE. The test data copied from QMK (qmk/testdata) and the Oryx-generated keymap in keymap/testdata/oryx keep their own licence, QMK's GPL-2.0-or-later. Firmware built here is QMK firmware and so GPL-2.0-or-later too; see The GPL above for how its source is offered.