快速入门
在 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 鉴权)
- 进入仓库 / 组织设置:
Settings → Secrets and variables → Actions - 添加新 Secret:
- Name:
MACRUNARA_INSTALLATION_ID - Secret:粘贴上一步拿到的 Installation ID 纯数字
- Name:
第 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
执行链路:
- push / PR 触发 GitHub Actions 事件
- Macrunara GitHub App 捕获事件,读取 Installation ID 鉴权
- 调度服务分配空闲 M4 arm64 Mac mini Runner 节点
- Runner 拉取代码,setup-action 完成环境参数校验输出
- 执行 xcodebuild 编译、单元测试
- 构建完成,日志、测试结果回传回 GitHub Actions 页面
第 5 步:查看构建结果
- 仓库页面打开 Actions 标签
- 点开本次工作流运行,实时查看控制台日志
- setup-action 会输出生效 region、timeout 等 step-summary 信息
- 编译产物可通过上传 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
下一步
- 了解 环境参数 Action
- 设置构建环境与缓存
- 配置归档导出 Action