跳到主要内容

快速入门

在 3 分钟内让你的第一个 macOS 构建在 Macrunara 上运行起来。无需在本地安装任何软件——所有配置都在 GitHub 上完成。

前置条件​

  • 一个 GitHub 账号(组织或个人均可,个人账号需开通 2FA)
  • 一个已启用 GitHub Actions 的仓库,且你有 Admin 权限(iOS / Android / Flutter / React Native 项目均可)
  • 配置阶段能正常访问 github.com(构建时的外网依赖由平台代理兜底)

第 1 步:安装 Macrunara GitHub App​

将 Macrunara GitHub App 安装至你的 GitHub 组织或目标仓库。

两种安装途径,任选其一:

  • 直接安装(推荐):打开 Macrunara App 安装页,点击 Install
  • Marketplace:进入 GitHub Marketplace 搜索 Macrunara,或打开组织 Settings → GitHub Apps

完成安装,授予对应仓库访问权限。

安装后打开 Organization Settings → Installed GitHub Apps → Macrunara → Configure,地址栏 URL 中的数字即为 Installation ID:

https://github.com/organizations/your-org/settings/installations/12345678
# ^^^^^^^^ Installation ID

第 2 步:配置仓库 Secret(提供 Installation ID 鉴权)​

  1. 进入仓库 / 组织设置:Settings → Secrets and variables → Actions
  2. 添加新 Secret:
    • Name:MACRUNARA_INSTALLATION_ID
    • Secret:粘贴上一步拿到的 Installation ID 纯数字

第 3 步:创建 Workflow 工作流文件​

在你仓库的 .github/workflows/ 目录下新建一个 .yml 文件(如 macrunara-ci.yml),写入以下内容,按注释修改 scheme / 路径:

name: macOS CI

on:
push:
branches: [main]

jobs:
build:
runs-on: [macos, arm64, macrunara]
steps:
- uses: actions/checkout@v4

- uses: macrunara/setup-action@v1
with:
installation-id: ${{ secrets.MACRUNARA_INSTALLATION_ID }}
region: auto

- name: Build
run: xcodebuild -scheme MyApp build # 改成你的 scheme

更多技术栈模板(Android / Flutter / React Native)见 快速上手 · 更新你的工作流。

第 4 步:提交配置,触发第一次构建​

git add .github/workflows/macrunara-ci.yml
git commit -m "Add Macrunara CI workflow with setup-action"
git push origin main

执行链路:

  1. push / PR 触发 GitHub Actions 事件
  2. Macrunara GitHub App 捕获事件,读取 Installation ID 鉴权
  3. 调度服务分配空闲 M4 arm64 Mac mini Runner 节点
  4. Runner 拉取代码,setup-action 完成环境参数校验输出
  5. 执行 xcodebuild 编译、单元测试
  6. 构建完成,日志、测试结果回传回 GitHub Actions 页面

第 5 步:查看构建结果​

  1. 仓库页面打开 Actions 标签
  2. 点开本次工作流运行,实时查看控制台日志
  3. setup-action 会输出生效 region、timeout 等 step-summary 信息
  4. 编译产物可通过上传 artifact 步骤保存

预期输出日志示例​

[setup-action] Macrunara setup start
[setup-action] installation-id verified, region:auto, timeout-minutes:30
[build] Using M4 arm64 Macrunara runner
[build] Checkout repository source code
[build] Running xcodebuild build
[build] Running xcodebuild test
[build] Test completed, passed: xx, failed: xx
[build] Build completed in xx min

下一步​