From 2ac44c6efcec84c95a104f2a481e984ac91e2dff Mon Sep 17 00:00:00 2001
From: UniXNU Docs <docs@unixnu.com>
Date: Wed, 21 Oct 2026 19:24:45 +0800
Subject: [PATCH] docs: describe the macOS runner workflow

---
 docs/building.md              | 27 +++++++++++++++++++++++++++
 docs/guide/requirements.md    |  2 ++
 docs/zh/building.md           | 27 +++++++++++++++++++++++++++
 docs/zh/guide/requirements.md |  2 ++
 4 files changed, 58 insertions(+)

diff --git a/docs/building.md b/docs/building.md
index 3b79e65..a3d6531 100644
--- a/docs/building.md
+++ b/docs/building.md
@@ -26,6 +26,33 @@ The device repository is remembered in `out/state.json` after the first `-D`.
 
 The boot image is `out/<board>/boot/boot.img` with `out/<board>/boot/boot.json` next to it. Options follow the subcommand.
 
+## macOS runner
+
+The kernel, userdata and Data seed steps call Xcode, `hdiutil` and `diskutil`. A fork can run them on a GitHub macOS runner without a local Mac.
+
+1. Fork the repository and enable Actions.
+2. Add the repository secret `UNIXNU_UNIQUE_CHIP_ID` when the board requires a platform seed.
+3. Run the `macOS build` workflow. Choose the device repository, ref, defconfig and steps.
+4. Download the artifacts from the run.
+
+| Input | Meaning |
+| --- | --- |
+| `device_repository` | Device repository as `owner/name` |
+| `device_ref` | Ref of the device repository |
+| `defconfig` | Defconfig name |
+| `steps` | `kernel`, `kernel userdata` or `kernel userdata payload` |
+| `ipsw_url` | Optional IPSW URL. An empty value uses `board.toml` |
+| `trust_cache_url` | Optional trust cache bundle URL |
+| `owner_trust_cache` | Treat the URL as an owner-signed bundle |
+| `data_seed_url` | Optional Data seed URL |
+| `grow_gib` | Grow the Data seed to this size |
+| `skip_setup` | Mark Setup as done in the Data seed |
+| `upload_userdata` | Upload the userdata image. The image is large |
+
+Add the repository secret `UNIXNU_DEVICE_TOKEN` when the device repository is private.
+
+The workflow runs kernel, userdata and payload. Package, firmware and boot image steps run on any OS and stay outside the workflow. Public repositories use the free macOS runner quota. Private repositories consume Actions minutes.
+
 ## Commands
 
 | Command | Action |
diff --git a/docs/guide/requirements.md b/docs/guide/requirements.md
index 81805df..a543855 100644
--- a/docs/guide/requirements.md
+++ b/docs/guide/requirements.md
@@ -21,6 +21,8 @@ The driver finds the keg-only Homebrew LLVM at `/opt/homebrew/opt/llvm/bin` with
 
 Network access is required for `unixnu fetch`, which updates the module submodules and fetches Apple source references and a Mu_Basecore tree.
 
+Without a Mac, the `macOS build` workflow runs the Mac-only steps on a GitHub macOS runner. See [Build](/building#macos-runner).
+
 ## External inputs
 
 These inputs live outside the UniXNU repositories.
diff --git a/docs/zh/building.md b/docs/zh/building.md
index 83d8b52..3ec27d7 100644
--- a/docs/zh/building.md
+++ b/docs/zh/building.md
@@ -26,6 +26,33 @@ git submodule update --init --recursive
 
 启动镜像位于 `out/<board>/boot/boot.img`，旁边的 `boot.json` 是报告。选项写在子命令之后。
 
+## macOS runner
+
+内核、userdata 和 Data 种子步骤调用 Xcode、`hdiutil` 和 `diskutil`。fork 后可以在 GitHub 的 macOS runner 上运行这些步骤，不需要本地 Mac。
+
+1. fork 仓库并启用 Actions。
+2. 板级需要平台种子时，添加仓库 secret `UNIXNU_UNIQUE_CHIP_ID`。
+3. 运行 `macOS build` workflow，选择设备仓库、ref、defconfig 和步骤。
+4. 从运行结果下载 artifact。
+
+| 输入 | 含义 |
+| --- | --- |
+| `device_repository` | 设备仓库，格式 `owner/name` |
+| `device_ref` | 设备仓库的 ref |
+| `defconfig` | defconfig 名称 |
+| `steps` | `kernel`、`kernel userdata` 或 `kernel userdata payload` |
+| `ipsw_url` | 可选 IPSW URL，空值使用 `board.toml` |
+| `trust_cache_url` | 可选 trust cache 包 URL |
+| `owner_trust_cache` | 把该 URL 当作 owner 签名的包 |
+| `data_seed_url` | 可选 Data 种子 URL |
+| `grow_gib` | 把 Data 种子增长到该大小 |
+| `skip_setup` | 在 Data 种子中标记 Setup 完成 |
+| `upload_userdata` | 上传 userdata 镜像。该镜像很大 |
+
+设备仓库为私有仓库时，添加仓库 secret `UNIXNU_DEVICE_TOKEN`。
+
+workflow 运行 kernel、userdata 和 payload。package、firmware 和 boot image 步骤可以在任意系统运行，不在 workflow 中。公开仓库使用免费的 macOS runner 配额，私有仓库消耗 Actions 分钟。
+
 ## 命令
 
 | 命令 | 作用 |
diff --git a/docs/zh/guide/requirements.md b/docs/zh/guide/requirements.md
index c9db8ce..724c37e 100644
--- a/docs/zh/guide/requirements.md
+++ b/docs/zh/guide/requirements.md
@@ -21,6 +21,8 @@
 
 `unixnu fetch` 需要网络，用于更新模块子模块并拉取 Apple 源码参考和 Mu_Basecore 树。
 
+没有 Mac 时，`macOS build` workflow 在 GitHub 的 macOS runner 上运行 Mac 专属步骤。见[构建](/zh/building#macos-runner)。
+
 ## 外部输入
 
 以下输入位于 UniXNU 仓库之外。