frontend-svelte/.gitea/QUICKSTART.md

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

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

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:

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

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

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

Tests failing?

# Run tests locally
yarn lint
yarn test
yarn build

📚 Documentation

For detailed information, see 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 for detailed documentation.