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:

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:

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:

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

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:

# 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):

   [actions]
   ENABLED = true
   

2. Or set via environment variable in docker-compose.yml:

   environment:
     - GITEA__actions__ENABLED=true
   

3. Restart Gitea:

   docker-compose restart gitea
   

---

Step 1: Install Xcode Command Line Tools

xcode-select --install

Step 2: Install Swift

Ensure Swift 6.0+ is installed:

swift --version

If not installed, download from swift.org or install via Xcode.

Step 3: Download Gitea Act Runner

Download the latest release from gitea/act_runner:

# 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

./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)

./act_runner daemon

Option B: Run as a Background Service (recommended)

Create a LaunchAgent to run the runner automatically:

mkdir -p ~/Library/LaunchAgents

Create the plist file:

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:

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

launchctl list | grep act_runner

Stop the Runner

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

Start the Runner

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

View Logs

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