swift-apple-intelligence-grpc/docs/macos-runner-setup.md

# Setting Up a macOS Self-Hosted Runner for Gitea Actions

This guide explains how to set up a self-hosted Gitea Actions runner on macOS for building, signing, and notarizing the Apple Intelligence Server app.

## Prerequisites

- A Mac (Intel or Apple Silicon) running macOS 13+
- Admin access to your Gitea instance
- Xcode Command Line Tools installed

## Step 1: Install Xcode Command Line Tools

```bash
xcode-select --install
```

## Step 2: Install Swift

Ensure Swift 6.0+ is installed:

```bash
swift --version
```

If not installed, download from [swift.org](https://swift.org/download/) or install via Xcode.

## Step 3: Download Gitea Act Runner

Download the latest release from [gitea/act_runner](https://gitea.com/gitea/act_runner/releases):

```bash
# For Apple Silicon (M1/M2/M3)
curl -L -o act_runner https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-darwin-arm64

# For Intel Mac
curl -L -o act_runner https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-darwin-amd64

# Make executable
chmod +x act_runner
```

## Step 4: Get Registration Token

1. Go to your Gitea repository
2. Navigate to **Settings** → **Actions** → **Runners**
3. Click **Create new Runner**
4. Copy the registration token

## Step 5: Register the Runner

```bash
./act_runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_REGISTRATION_TOKEN \
  --name "macos-runner" \
  --labels "macos,macos-latest,self-hosted"
```

When prompted:
- **Runner name:** `macos-runner` (or any name you prefer)
- **Labels:** `macos,macos-latest,self-hosted`

This creates a `.runner` configuration file in the current directory.

## Step 6: Run the Runner

### Option A: Run in Foreground (for testing)

```bash
./act_runner daemon
```

### Option B: Run as a Background Service (recommended)

Create a LaunchAgent to run the runner automatically:

```bash
mkdir -p ~/Library/LaunchAgents
```

Create the plist file:

```bash
cat > ~/Library/LaunchAgents/com.gitea.act_runner.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.gitea.act_runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/Users/YOUR_USERNAME/act_runner/act_runner</string>
        <string>daemon</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/Users/YOUR_USERNAME/act_runner</string>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/YOUR_USERNAME/act_runner/runner.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/YOUR_USERNAME/act_runner/runner.error.log</string>
</dict>
</plist>
EOF
```

**Important:** Replace `YOUR_USERNAME` with your actual macOS username.

Load the service:

```bash
launchctl load ~/Library/LaunchAgents/com.gitea.act_runner.plist
```

## Step 7: Verify Runner is Connected

1. Go to your Gitea repository
2. Navigate to **Settings** → **Actions** → **Runners**
3. Your runner should appear as **Online**

## Managing the Runner

### Check Status

```bash
launchctl list | grep act_runner
```

### Stop the Runner

```bash
launchctl unload ~/Library/LaunchAgents/com.gitea.act_runner.plist
```

### Start the Runner

```bash
launchctl load ~/Library/LaunchAgents/com.gitea.act_runner.plist
```

### View Logs

```bash
tail -f ~/act_runner/runner.log
tail -f ~/act_runner/runner.error.log
```

## Security Considerations

1. **Dedicated User:** Consider creating a dedicated macOS user for the runner
2. **Keychain Access:** The runner needs access to the keychain for code signing
3. **Network:** Ensure the Mac has reliable network access to your Gitea instance
4. **Updates:** Keep the runner updated to the latest version

## Troubleshooting

### Runner Not Connecting

- Check firewall settings
- Verify the Gitea instance URL is correct
- Ensure the registration token hasn't expired

### Code Signing Fails

- Ensure certificates are installed in the login keychain
- Check that the runner has keychain access
- Verify certificate names match the workflow

### Build Fails with Swift Errors

- Ensure Xcode Command Line Tools are installed
- Check Swift version compatibility
- Clear the build cache: `swift package clean`

## Recommended Directory Structure

```
~/act_runner/
├── act_runner          # The runner binary
├── .runner             # Runner configuration
├── runner.log          # Standard output log
└── runner.error.log    # Error log
```