QMK Firmwareを簡単にビルド！ カスタムGithub ActionをMarketPlaceに公開しました

[経緯]

• 環境構築のハードル:
  • 久々にQMK Firmwareでキーマップを変更しようと思ったが、毎回環境構築手順を忘れてしまいます。
  • QMK環境構築に関する記事も古かったり内容が曖昧だったりして、再現性が低くて困っていました。
• 環境の維持:
  • たまにしかファームウェアを作成しないので、環境を維持するわけにもいかない
  • 毎回サーバに入ってビルドして、作成した.hexファイルをローカルに複製するのが面倒。
• 周囲の状況:
  • 周りの自作キーボードの同僚たちは、ビルド環境構築のハードルが高いため、QMK Configuratorでファームウェアを作成して、keymapをごりごりカスタマイズしていないようです。
• 環境の更新:
  • qmk/qmk_base_container, qmk/qmk_cliはdebian-11でもうすぐEOLとなるため、debian-12版で作成しました。

[解決策]

これらの問題を解決するために、自作のGithub Actionだけでビルドできるようにしてましたが、
ついでにカスタムGithub Actionsの作成ノウハウを学べるので、公式qmk_base_container, qmk_cliをベースにし、qmk_base_container, qmk_cliも含めて更新を行い、カスタムGithub ActionsをMarketplaceを公開しました。

[QMKファームウェアビルド カスタムGithub Action]

URL: qmk_build

ディレクトリ構造

以下のディレクトリ構造でgitリポジトリをGithubに構築します。

- /
    - .github/workflows/
        - build.yml ... サンプルから複製
    - keyboards/
        - [自身のキーボードフォルダ]/ ... qmk_firmware.git/keyboards/以下から複製するのが早い
            - keymaps/[自身のキーマップフォルダ] ... keymaps/defaultを複製してカスタマイズするなど
            - rules.mk, config.h ... 必要であれば修正

.github/workflows/build.ymlの設定

以下は.github/workflows/build.ymlの例です。

name: Sample QMK Firmware Build Action

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:

      # ご自身のリポジトリをclone
      - name: Checkout code
        uses: actions/checkout@v4

      # ビルドしたいkeyboard, rev, keymapを指定
      - name: QMK Build firmware Action
        uses: ijikeman/qmk_build@v0.0.1
        with:
          keyboard: 'plunck'
          rev: 'rev1'
          keymap: 'default'

      # 複数指定可能
      - name: QMK Build firmware Action
        uses: ijikeman/qmk_build@v0.0.1
        with:
          qmk_firmware_version: 0.27.0 # v0.0.1では0.28.0がDockerimageに含まれていますが、別のバージョンでビルドしたい場合は指定します
          keyboard: 'plunck'
          rev: 'rev1'
          keymap: 'original_keymap'

      # 生成された.hexファイルをartifactとしてアーカイブ保存
      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: firmware
          path: ${{ github.workspace }}/output/*.hex

ビルド後の結果

Githubの自身のリポジトリにpushした後、Actionsに移動しビルドが成功すると、.zipファイルが生成されており、.hexファイルが内包されています。