# 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' Label com.gitea.act_runner ProgramArguments /Users/YOUR_USERNAME/act_runner/act_runner daemon WorkingDirectory /Users/YOUR_USERNAME/act_runner RunAtLoad KeepAlive StandardOutPath /Users/YOUR_USERNAME/act_runner/runner.log StandardErrorPath /Users/YOUR_USERNAME/act_runner/runner.error.log 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 ```