# Gitea Local CI — Self-Hosted CI for ByteLyst Ecosystem

## Overview

Self-hosted Gitea + act_runner replaces GitHub Actions (billing blocked). Runs CI jobs directly on your Mac — no Docker required.

## Architecture

| Component      | Port | Purpose                          |
| -------------- | ---- | -------------------------------- |
| **Gitea**      | 3300 | Git hosting + Actions engine     |
| **act_runner** | —    | Executes CI jobs on host (macOS) |

- **GitHub (`origin`)** — unchanged, primary code hosting
- **Gitea (`gitea`)** — secondary remote, triggers local CI on push

## Credentials

- **URL:** http://localhost:3300
- **Username:** `bytelyst`
- **Password:** `bytelyst123`

## Quick Commands

```bash
# Start services
brew services start gitea
brew services start act_runner

# Stop services
brew services stop act_runner
brew services stop gitea

# Check status
brew services list | grep -E "gitea|act_runner"

# Push to trigger CI
git push gitea main
```

## Config Locations

| File                | Path                                          |
| ------------------- | --------------------------------------------- |
| Gitea config        | `/opt/homebrew/var/gitea/custom/conf/app.ini` |
| Runner config       | `/opt/homebrew/etc/act_runner/config.yaml`    |
| Runner registration | `/opt/homebrew/var/lib/act_runner/.runner`    |
| Runner stderr log   | `/opt/homebrew/var/log/act_runner.err`        |
| Gitea data          | `/opt/homebrew/var/gitea/data/`               |
| Gitea logs          | `/opt/homebrew/var/gitea/log/`                |
| Job work dir        | `~/.cache/act/`                               |

## Key Settings

- **Runner capacity:** 1 (sequential jobs — prevents concurrent builds conflicting on shared common-plat)
- **Runner labels:** `ubuntu-latest:host`, `macos-latest:host`, `macos-15:host`, `self-hosted:host`
- **Gitea port:** 3300 (avoids conflict with Next.js dev servers on 3000)
- **Actions URL:** `github` (Gitea resolves action references via GitHub mirror)
- **Git credential helper:** Configured globally for `localhost:3300` to auto-authenticate

## How It Works

1. You `git push gitea main` from any repo
2. Gitea detects `.gitea/workflows/ci.yml` in the pushed code
3. act_runner picks up the job and runs it on your Mac (host mode)
4. Jobs have access to node, pnpm, python, etc. from your system PATH
5. `@bytelyst/*` packages are built from the local common-plat checkout (`/Users/sd9235/code/mygh/learning_ai_common_plat`)

## Repos Configured

All 14 repos have a `gitea` remote → `http://localhost:3300/bytelyst/<repo>.git`.

11 repos with CI workflows (`.gitea/workflows/ci.yml`):

| Repo                                | Jobs                              |
| ----------------------------------- | --------------------------------- |
| `learning_ai_common_plat`           | Build, Test & Typecheck           |
| `learning_ai_clock`                 | Backend + Web                     |
| `learning_ai_trails`                | Backend + SDK + Web               |
| `learning_ai_flowmonk`              | Backend + Web                     |
| `learning_ai_notes`                 | Backend + Web + Mobile            |
| `learning_ai_fastgap`               | Mobile + Backend + Web            |
| `learning_ai_jarvis_jr`             | Backend + Web                     |
| `learning_ai_peakpulse`             | Backend                           |
| `learning_ai_local_memory_gpt`      | Backend + Web                     |
| `learning_voice_ai_agent`           | Backend + Python + User Dashboard |
| `learning_multimodal_memory_agents` | Backend + Web + KMP               |

3 repos without CI workflows (docs/config only):

- `learning_ai_auth_app`, `learning_ai_smart_auth`, `learning_ai_productivity_web`

GitHub Actions disabled via `.github/workflows/ci.yml.disabled` in all repos.

## Differences from GitHub Actions

| Feature              | GitHub Actions                                   | Gitea Actions                     |
| -------------------- | ------------------------------------------------ | --------------------------------- |
| Runner               | Ubuntu container                                 | macOS host                        |
| common-plat checkout | `actions/checkout` with `repository:` + `GH_PAT` | Already on disk at `$COMMON_PLAT` |
| Node setup           | `actions/setup-node@v4`                          | Already installed via brew        |
| pnpm setup           | `pnpm/action-setup@v4`                           | Already installed via brew        |
| Concurrency          | Free tier limited                                | Unlimited (local)                 |

## Push to Both Remotes

To push to both GitHub and Gitea in one command, add a script alias:

```bash
# Add to ~/.zshrc
gpush() { git push origin main && git push gitea main; }
```

## Troubleshooting

### Runner not picking up jobs

```bash
brew services restart act_runner
# Check logs
tail -50 /opt/homebrew/var/log/act_runner.log
```

### Gitea not responding

```bash
brew services restart gitea
curl -s http://localhost:3300/api/v1/version
```

### Re-register runner

```bash
brew services stop act_runner
rm /opt/homebrew/var/act_runner/.runner
TOKEN=$(curl -s -u "bytelyst:bytelyst123" http://127.0.0.1:3300/api/v1/admin/runners/registration-token | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
cd /opt/homebrew/var/act_runner && /opt/homebrew/opt/act_runner/bin/act_runner register --config /opt/homebrew/etc/act_runner/config.yaml --instance http://127.0.0.1:3300 --token "$TOKEN" --name bytelyst-mac --no-interactive
brew services start act_runner
```