Mathias Beaulieu-Duncan 8e53dee03c Add CI/CD pipeline and documentation

- Add Gitea Actions workflow for automated releases
  - Builds release binary
  - Signs app with Developer ID
  - Creates and signs DMG
  - Notarizes with Apple
  - Uploads to release

- Add documentation:
  - macos-runner-setup.md: Self-hosted runner setup guide
  - pipeline-configuration.md: Secrets and pipeline config guide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-30 04:35:36 -05:00

4.5 KiB

Raw Blame History

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

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

Go to your Gitea repository
Navigate to Settings → Actions → Runners
Click Create new Runner
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

Go to your Gitea repository
Navigate to Settings → Actions → Runners
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

Dedicated User: Consider creating a dedicated macOS user for the runner
Keychain Access: The runner needs access to the keychain for code signing
Network: Ensure the Mac has reliable network access to your Gitea instance
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

4.5 KiB Raw Blame History