跳到主要内容

常见问题

Macrunara 常见问题,按「问题 → 原因 → 解决」格式整理。

Q: 任务一直停在 queued,没有任何节点接单,怎么办?​

按以下顺序排查:

  1. 检查标签拼写:逐字符核对 runs-on,常见错误:macruna、mac-runara、macrunara-app(旧写法,已废弃)。
  2. 检查大小写:标签区分大小写,必须全小写:macos ✅ / MacOS ❌。
  3. 检查是否子集:runs-on 中的每个标签都必须在节点上报集合内。逐一删掉可疑标签(尤其是 self-hosted、macos-latest)再触发验证。
  4. 检查 YAML 写法:数组形式 runs-on: [macos, arm64, macrunara] 与多行形式等价;不要写成逗号拼接的单个字符串 runs-on: "macos, arm64, macrunara"(这会被当成一个标签)。
  5. 确认队列无历史残留:GitHub 队列为 FIFO,若队列中有带错误标签的旧 job 占位,请先取消(Actions 页面 → Cancel workflow)。
  6. 确认订阅与配额:登录 Macrunara 管理后台确认订阅有效、配额未满(排队超过 5 分钟时的常规检查项)。

setup-action 报 installation-id 校验失败​

原因:installation-id 参数必须为纯数字。传入 URL、App ID 或 Client ID 都会校验失败。

解决:按以下步骤获取正确的 Installation ID:

  1. 打开 Organization Settings → Installed GitHub Apps → Macrunara → Configure。
  2. 地址栏 URL 末尾的数字即为 Installation ID:
https://github.com/organizations/your-org/settings/installations/12345678
# ^^^^^^^^ Installation ID
  1. 只传入这串数字:
- uses: macrunara/setup-action@v1
with:
installation-id: ${{ secrets.MACRUNARA_INSTALLATION_ID }}

Secret 未配置​

原因:缺少 MACRUNARA_INSTALLATION_ID secret,${{ secrets.MACRUNARA_INSTALLATION_ID }} 解析为空值,校验失败。

解决:在仓库中进入 Settings → Secrets and variables → Actions,添加:

  • Name:MACRUNARA_INSTALLATION_ID
  • Secret:你的 Installation ID

Q: 为什么不像 GitHub 托管 Runner 那样写 macos-latest?​

Macrunara 节点是自托管性质的 ephemeral runner,标签集合由节点注册时上报决定,与 GitHub 托管 Runner 的标签体系无关。平台选择 macos / arm64 / macrunara 三标签,分别表达"操作系统"、"CPU 架构"、"平台归属"三个维度。

Q: 能否只写 runs-on: macos?​

可以(是子集,合法),但不推荐:仅写 macos 无法区分其他可能上报 macos 标签的 Runner。推荐始终使用 [macos, arm64, macrunara] 完整写法。

Q: setup-action 会帮我修改 Runner 标签吗?​

不会,也不能。 Runner 标签在注册时即固定,job 内无法动态修改(GitHub Actions 不存在此类机制)。macrunara/setup-action@v1 的作用是品牌横幅、参数校验与环境信息导出,属于可选步骤。标签只能由你在 workflow 的 runs-on 字段中正确声明。