From 647a433c256ca4c8502a3d63cb091a7f9c18dd48 Mon Sep 17 00:00:00 2001
From: Haobo Gu <haobogu@outlook.com>
Date: Mon, 13 Jul 2026 19:57:26 +0800
Subject: [PATCH] ci: expose rmk_version input and scope the push trigger

Surface the reusable workflow's rmk_version input via workflow_dispatch so forks can build against a released RMK version (default: main); previously every fork was stuck on main because this file never passed it through.

Scope the push trigger to keyboard.toml/vial.json so README/other edits don't trigger a firmware rebuild. Add a README covering cloud builds and the version knob.
---
 .github/workflows/build.yml | 12 +++++++++++-
 README.md                   | 18 ++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 README.md

diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index fc34d96..a3d38aa 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -1,9 +1,17 @@
 name: Build RMK firmware
 on:
   workflow_dispatch:
+    inputs:
+      rmk_version:
+        description: "RMK version to build against (default: main; or a version listed in rmk-template/version-mapping.json, e.g. 0.8)"
+        default: "main"
+        required: false
   push:
+    # Rebuild only when the config that feeds the firmware changes — not on
+    # README edits, etc. Add paths here if you keep extra config files.
     paths:
-      - "**"
+      - "keyboard.toml"
+      - "vial.json"
 
 jobs:
   build:
@@ -11,3 +19,5 @@ jobs:
     with:
       keyboard_toml_path: "keyboard.toml"
       vial_json_path: "vial.json"
+      # Manual runs use the dispatch input; pushes build against main.
+      rmk_version: ${{ github.event.inputs.rmk_version || 'main' }}
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9669603
--- /dev/null
+++ b/README.md
@@ -0,0 +1,18 @@
+# RMK firmware project template
+
+Fork this repository to build [RMK](https://github.com/HaoboGu/rmk) keyboard firmware in the cloud — no local Rust toolchain required.
+
+## Use it
+
+1. Click **Use this template → Create a new repository**.
+2. Edit `keyboard.toml` (your keyboard's layout, pins, and enabled features) and `vial.json` (the Vial matrix definition). See the [configuration guide](https://rmk.rs/docs/configuration.html).
+3. Commit. GitHub Actions builds your firmware automatically.
+4. Open the **Actions** tab and download the compiled firmware from the run's **Artifacts** (`.uf2`, `.hex`, or `.bin`).
+
+A build runs on every push that changes `keyboard.toml` or `vial.json`.
+
+## Choose the RMK version
+
+By default the firmware builds against RMK's `main`. To pin a released version, run the workflow manually: **Actions → Build RMK firmware → Run workflow**, and set **rmk_version** to a version listed in [`version-mapping.json`](https://github.com/HaoboGu/rmk-template/blob/main/version-mapping.json) (e.g. `0.8`).
+
+> The feature set is derived from `keyboard.toml`. Pinning an older `rmk_version` may not match the current config schema, so `main`/`latest` is the supported combination.