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

## Network Setup (Local Gitea in Docker on Linux)

If your Gitea instance is running in Docker on a Linux server on your local network, follow these steps to ensure the Mac runner can connect.

### 1. Find Your Linux Server's IP Address

On the Linux server:

```bash
hostname -I | awk '{print $1}'
# Example output: 192.168.1.50
```

### 2. Ensure Gitea is Accessible

Verify Gitea's Docker container exposes the correct ports. In your `docker-compose.yml`:

```yaml
services:
  gitea:
    image: gitea/gitea:latest
    ports:
      - "3000:3000"   # Web UI
      - "22:22"       # SSH (optional)
    environment:
      - GITEA__server__ROOT_URL=http://192.168.1.50:3000/
      - GITEA__server__DOMAIN=192.168.1.50
      - GITEA__server__SSH_DOMAIN=192.168.1.50
```

**Important:** Replace `192.168.1.50` with your Linux server's actual IP.

If you're using a reverse proxy (Nginx, Traefik), ensure it's configured to accept connections from your local network.

### 3. Test Connectivity from Mac

From your Mac, verify you can reach Gitea:

```bash
# Test web access
curl -I http://192.168.1.50:3000

# Or if using a domain name
ping gitea.local
curl -I http://gitea.local:3000
```

### 4. (Optional) Add Local DNS Entry

For easier access, add the server to your Mac's hosts file:

```bash
sudo nano /etc/hosts
```

Add:
```
192.168.1.50    gitea.local
```

Now you can use `http://gitea.local:3000` instead of the IP address.

### 5. Linux Firewall Configuration

Ensure the Linux server's firewall allows connections on port 3000:

```bash
# UFW (Ubuntu/Debian)
sudo ufw allow 3000/tcp

# firewalld (CentOS/Fedora)
sudo firewall-cmd --permanent --add-port=3000/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
```

### 6. Enable Gitea Actions

In your Gitea instance, ensure Actions is enabled:

1. Edit `app.ini` (usually in `/data/gitea/conf/app.ini` in Docker):
   ```ini
   [actions]
   ENABLED = true
   ```

2. Or set via environment variable in `docker-compose.yml`:
   ```yaml
   environment:
     - GITEA__actions__ENABLED=true
   ```

3. Restart Gitea:
   ```bash
   docker-compose restart gitea
   ```

---

## 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
```