# Gitea Actions Quick Start Guide

This is a quick reference guide for getting started with the GlyphDiff CI/CD pipeline.

## 🚀 Quick Start (5 Minutes)

### 1. Verify Actions Enabled

1. Go to your Gitea instance → Site Admin → Actions
2. Ensure Actions is enabled

### 2. Enable Actions for Repository

1. Go to repository → Settings → Actions
2. Enable Actions (if not already enabled)

### 3. Commit and Push Workflows

```bash
git add .gitea/
git commit -m "Add Gitea Actions CI/CD workflows"
git push origin main
```

### 4. Verify Workflows Run

- Go to repository → Actions tab
- You should see workflows running on push

## 📋 Workflow Summary

| Workflow   | What It Does                            | When It Runs                      |
| ---------- | --------------------------------------- | --------------------------------- |
| **lint**   | Runs oxlint & dprint check              | Push/PR to main/develop/feature/* |
| **test**   | Type check & Playwright E2E tests       | Push/PR to main/develop/feature/* |
| **build**  | Builds SvelteKit production bundle      | Push to main/develop, PRs         |
| **deploy** | Deploys to production (configure first) | Push to main, manual trigger      |

## 🔧 Self-Hosted Runner Setup (Linux)

### Install act_runner

```bash
wget -O /usr/local/bin/act_runner https://gitea.com/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
chmod +x /usr/local/bin/act_runner
```

### Register Runner

1. Go to repo → Settings → Actions → Runners
2. Click "New Runner"
3. Copy registration token
4. Run:

```bash
act_runner register \
  --instance https://your-gitea-instance.com \
  --token YOUR_TOKEN \
  --name "linux-runner-1" \
  --labels ubuntu-latest,linux,docker \
  --no-interactive
```

### Run as Service

```bash
# Create systemd service
sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=git
WorkingDirectory=/var/lib/gitea-runner
ExecStart=/usr/local/bin/act_runner daemon
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner

# Check status
sudo systemctl status gitea-runner
```

## 🔑 Secrets Setup (For Deployment)

Go to repo → Settings → Secrets → Actions

### For Docker Deployment

```
REGISTRY_URL=registry.example.com
REGISTRY_USERNAME=username
REGISTRY_PASSWORD=password
```

### For SSH Deployment

```
DEPLOY_HOST=server.example.com
DEPLOY_USER=deploy
DEPLOY_SSH_KEY=-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
```

### For Vercel Deployment

```
VERCEL_TOKEN=your-vercel-token
VERCEL_ORG_ID=your-org-id
VERCEL_PROJECT_ID=your-project-id
```

## 🐛 Troubleshooting

### Workflows not running?

- Check Actions is enabled in Gitea
- Verify `.gitea/workflows/` directory exists
- Check workflow YAML syntax

### Runner offline?

```bash
sudo systemctl status gitea-runner
sudo journalctl -u gitea-runner -f
```

### Tests failing?

```bash
# Run tests locally
yarn lint
yarn test
yarn build
```

## 📚 Documentation

For detailed information, see [README.md](./README.md)

## 🎯 Common Tasks

### Trigger manual workflow run

1. Go to Actions tab
2. Select workflow (e.g., Build)
3. Click "Run workflow"
4. Select branch and click "Run workflow"

### View workflow logs

1. Go to Actions tab
2. Click on workflow run
3. Click on job to view logs

### Download artifacts

1. Go to workflow run
2. Scroll to "Artifacts" section
3. Download desired artifact (e.g., playwright-report, build-artifacts)

### Re-run failed workflow

1. Go to failed workflow run
2. Click "Re-run failed jobs"

## 🔄 Workflow States

| Status         | Meaning                      |
| -------------- | ---------------------------- |
| ⏳ Queued      | Waiting for available runner |
| 🔄 In Progress | Currently running            |
| ✅ Success     | All checks passed            |
| ❌ Failed      | One or more checks failed    |
| ⚠️ Cancelled    | Workflow was cancelled       |

## 📊 Workflow Duration Estimates

| Workflow          | Typical Duration      |
| ----------------- | --------------------- |
| lint              | 30-60 seconds         |
| test (type-check) | 45-90 seconds         |
| test (e2e)        | 2-5 minutes           |
| build             | 1-3 minutes           |
| deploy            | Varies (2-10 minutes) |

---

**Need Help?** See the full [README.md](./README.md) for detailed documentation.