# DevOps CI/CD Pipeline Summary

This document provides an overview of the continuous integration and deployment (CI/CD) pipeline for the GlyphDiff SvelteKit project using Gitea Actions.

## 📋 Table of Contents

- [Pipeline Overview](#pipeline-overview)
- [Quick Reference](#quick-reference)
- [Architecture](#architecture)
- [Workflow Details](#workflow-details)
- [Deployment Strategy](#deployment-strategy)
- [Monitoring & Observability](#monitoring--observability)
- [Self-Hosted Runner Setup](#self-hosted-runner-setup)
- [Getting Started](#getting-started)

## Pipeline Overview

### DevOps Solution: Gitea Actions CI/CD Pipeline

#### Architecture Overview

The GlyphDiff project uses Gitea Actions (GitHub Actions compatible) for CI/CD on a self-hosted Gitea instance. The pipeline is designed to be:

- **Automated**: Every push and PR triggers validation workflows
- **Fast**: Caching strategies optimize execution time
- **Reliable**: Multiple quality gates ensure code quality
- **Secure**: Secrets management and least-privilege access
- **Observable**: Artifacts and logs for debugging

#### CI/CD Pipeline Stages

1. **Source**: Trigger on commits, PRs, or manual dispatch
2. **Lint**: Code quality checks (oxlint, dprint)
3. **Test**: Type checking and E2E tests (Playwright)
4. **Build**: Production build verification
5. **Deploy**: Automated deployment (optional/template)

#### Quality Gates

- ✅ All linting checks must pass
- ✅ Type checking must have no errors
- ✅ All E2E tests must pass
- ✅ Production build must complete successfully
- ✅ Health check on preview server must succeed

## Quick Reference

| Workflow     | Purpose                | Trigger      | Duration |
| ------------ | ---------------------- | ------------ | -------- |
| `lint.yml`   | Code quality checks    | Push/PR      | 30-60s   |
| `test.yml`   | Type check & E2E tests | Push/PR      | 3-6min   |
| `build.yml`  | Production build       | Push/PR      | 1-3min   |
| `deploy.yml` | Deployment to prod     | Push to main | 2-10min  |

### Branch Strategy

| Branch      | Workflows         | Deployment    |
| ----------- | ----------------- | ------------- |
| `main`      | All workflows     | Yes (on push) |
| `develop`   | Lint, Test, Build | No            |
| `feature/*` | Lint, Test        | No            |

### Environment Configuration

| Environment | Branch    | Purpose             |
| ----------- | --------- | ------------------- |
| Production  | `main`    | Live deployment     |
| Development | `develop` | Integration testing |

## Architecture

### Pipeline Flowchart

```
┌─────────────┐
│   Push/PR   │
└──────┬──────┘
       │
       ├──────────────┬──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
┌───────────┐   ┌───────────┐   ┌───────────┐   ┌───────────┐
│   Lint    │   │   Test    │   │  Build    │   │  Deploy   │
│  (30s)    │   │ (3-6min)  │   │ (1-3min)  │   │ (2-10min) │
└───────────┘   └───────────┘   └───────────┘   └───────────┘
       │              │              │              │
       │              │              │              │
       └──────────────┴──────────────┴──────────────┘
                      │
                      ▼
             ┌────────────────┐
             │  All Pass ✅   │
             └────────────────┘
```

### Technology Stack

| Component           | Technology    | Version |
| ------------------- | ------------- | ------- |
| **CI/CD Platform**  | Gitea Actions | Latest  |
| **Runner**          | act_runner    | 0.2.11+ |
| **Package Manager** | Yarn          | Latest  |
| **Runtime**         | Node.js       | 20.x    |
| **Framework**       | SvelteKit     | 2.49.1+ |
| **Build Tool**      | Vite          | 7.2.6+  |
| **Linter**          | oxlint        | 1.35.0+ |
| **Formatter**       | dprint        | 0.50.2+ |
| **E2E Testing**     | Playwright    | 1.57.0+ |
| **TypeScript**      | TypeScript    | 5.9.3+  |
| **Git Hooks**       | lefthook      | 2.0.13+ |

## Workflow Details

### 1. Lint Workflow (`lint.yml`)

**Purpose**: Ensure code quality and formatting standards

**Checks**:

- `oxlint` - Fast JavaScript/TypeScript linting
- `dprint check` - Code formatting verification

**Triggers**:

- Push to `main`, `develop`, `feature/*`
- Pull requests to `main`, `develop`
- Manual dispatch

**Features**:

- Yarn caching for fast dependency installation
- Concurrency control (cancels in-progress runs)
- ~30-60 second execution time

**Quality Gate**:

```yaml
Exit on: Failure
Prevents: Build and deployment
```

---

### 2. Test Workflow (`test.yml`)

**Purpose**: Verify type safety and application behavior

**Jobs**:

#### Type Check Job

- `tsc --noEmit` - TypeScript type checking
- `svelte-check --threshold warning` - Svelte component type checking

#### E2E Tests Job

- Install Playwright browsers with system dependencies
- Run E2E tests using Playwright
- Upload test report artifacts (7-day retention)
- Upload screenshots on test failure

**Triggers**: Same as lint workflow

**Artifacts**:

- `playwright-report` - HTML test report
- `playwright-screenshots` - Screenshots from failed tests

**Quality Gates**:

```yaml
Exit on: Failure
Prevents: Build and deployment
```

---

### 3. Build Workflow (`build.yml`)

**Purpose**: Verify production build success

**Steps**:

1. Setup Node.js v20 with Yarn caching
2. Install dependencies with `--frozen-lockfile`
3. Run `svelte-kit sync` to prepare SvelteKit
4. Build with `NODE_ENV=production`
5. Upload build artifacts (`.svelte-kit/output`, `.svelte-kit/build`)
6. Run preview server and health check

**Triggers**:

- Push to `main` or `develop`
- Pull requests to `main` or `develop`
- Manual dispatch

**Artifacts**:

- `build-artifacts` - Compiled SvelteKit output (7-day retention)

**Quality Gate**:

```yaml
Exit on: Failure
Prevents: Deployment
```

---

### 4. Deploy Workflow (`deploy.yml`)

**Purpose**: Automated deployment to production

**Current State**: Template configuration (requires customization)

**Pre-deployment Checks**:

- Must pass linting workflow
- Must pass testing workflow
- Must pass build workflow

**Triggers**:

- Push to `main` branch
- Manual dispatch with environment selection (staging/production)

**Deployment Options** (uncomment one):

1. **Docker Container Registry**
   - Build and push Docker image
   - Supports GitHub Actions cache
   - Requires: `REGISTRY_URL`, `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`

2. **SSH Deployment**
   - Deploy to server via SSH
   - Supports custom deployment scripts
   - Requires: `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`

3. **Vercel**
   - Deploy to Vercel platform
   - Zero-configuration deployment
   - Requires: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`

**Features**:

- Environment-based deployment (staging/production)
- Post-deployment health check (template)
- Prevents concurrent deployments (concurrency group)

## Deployment Strategy

**Strategy**: Manual Trigger with Environment Gates (Template)

### Description

The deployment workflow is designed as a template that can be customized based on your deployment needs. It requires manual approval and successful completion of all CI checks before deployment.

### Pros

- ✅ Flexibility to choose deployment method
- ✅ Multiple deployment options (Docker, SSH, Vercel)
- ✅ Environment separation (staging/production)
- ✅ Pre-deployment gates ensure quality
- ✅ Prevents concurrent deployments

### Cons

- ⚠️ Requires manual configuration
- ⚠️ No automated rollback mechanism (can be added)
- ⚠️ No blue-green deployment (can be implemented)

### Recommended Future Enhancements

1. **Automated Rollback**: Detect failures and auto-rollback
2. **Blue-Green Deployment**: Zero downtime deployment
3. **Canary Releases**: Gradual traffic rollout
4. **Slack Notifications**: Notify team on deployment status
5. **Deployment Dashboard**: Visual deployment tracking

## Monitoring & Observability

### Metrics

**Workflow Execution**:

- Success/failure rates
- Execution duration
- Resource usage (CPU, memory)
- Queue times

**Application Metrics** (to be added):

- Response times
- Error rates
- Throughput
- Custom business metrics

### Logs

**Workflow Logs**:

- Available in Gitea Actions UI
- Retention: 90 days (configurable)
- Searchable and filterable

**Application Logs** (to be added):

- Centralized log aggregation (ELK, Loki)
- Structured logging (JSON)
- Log levels (debug, info, warn, error)

### Alerts

**Current**:

- Email notifications on workflow failure (Gitea feature)

**Recommended**:

- Slack/Mattermost integration
- PagerDuty for critical failures
- Health check alerts (uptime monitoring)

## Self-Hosted Runner Setup

### Runner Architecture

```
┌─────────────────────────────────────┐
│         Gitea Instance              │
│   (Actions Enabled, Self-Hosted)     │
└──────────────┬──────────────────────┘
               │
               │ HTTPS/Webhook
               │
               ▼
┌─────────────────────────────────────┐
│      act_runner (Linux/Ubuntu)       │
│      - Systemd service               │
│      - Labels: ubuntu-latest         │
│      - Docker enabled                │
└──────────────┬──────────────────────┘
               │
               │ Executes workflows
               │
               ▼
┌─────────────────────────────────────┐
│     Docker Containers                │
│  - Node.js 20 container              │
│  - Playwright browsers               │
│  - Build environment                 │
└─────────────────────────────────────┘
```

### Installation Steps

#### 1. 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
```

#### 2. Register Runner

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

#### 3. Configure as Service

```bash
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
```

#### 4. Start Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner
```

### Runner Requirements

| Requirement | Minimum       | Recommended   |
| ----------- | ------------- | ------------- |
| **CPU**     | 2 cores       | 4 cores       |
| **RAM**     | 2 GB          | 4 GB          |
| **Disk**    | 20 GB         | 50 GB         |
| **OS**      | Ubuntu 20.04+ | Ubuntu 22.04+ |
| **Docker**  | 20.10+        | 24.0+         |

## Getting Started

### Prerequisites

1. ✅ Gitea instance with Actions enabled
2. ✅ Self-hosted runner configured (optional for testing)
3. ✅ Repository with workflows in `.gitea/workflows/`
4. ✅ Secrets configured (for deployment)

### Quick Start

1. **Verify Gitea Actions is enabled**
   - Go to Site Admin → Actions
   - Ensure Actions is enabled

2. **Enable Actions for repository**
   - Go to repository → Settings → Actions
   - Enable Actions

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
   - View workflow execution logs

5. **Configure deployment** (optional)
   - Go to Settings → Secrets → Actions
   - Add deployment secrets
   - Uncomment deployment method in `deploy.yml`

### Validation Checklist

- [ ] Workflows trigger on push/PR
- [ ] Lint workflow passes
- [ ] Test workflow passes
- [ ] Build workflow passes
- [ ] Artifacts are uploaded
- [ ] Runner is online (if self-hosted)
- [ ] Caching is working (check logs)
- [ ] Secrets are configured (for deployment)

## Documentation Links

- **Full Documentation**: [`.gitea/README.md`](.gitea/README.md)
- **Quick Start**: [`.gitea/QUICKSTART.md`](.gitea/QUICKSTART.md)
- **Workflow Files**: [`.gitea/workflows/`](.gitea/workflows/)
- **Gitea Actions Docs**: https://docs.gitea.com/usage/actions/overview
- **act_runner Docs**: https://docs.gitea.com/usage/actions/act-runner

## Status Badges

Add to your `README.md`:

```markdown
![Lint](https://your-gitea-instance.com/username/glyphdiff/actions/badges/workflow/lint.yml/badge.svg)
![Test](https://your-gitea-instance.com/username/glyphdiff/actions/badges/workflow/test.yml/badge.svg)
![Build](https://your-gitea-instance.com/username/glyphdiff/actions/badges/workflow/build.yml/badge.svg)
```

## Next Steps

1. **Customize Deployment**: Choose and configure deployment method
2. **Add Notifications**: Set up Slack/Mattermost alerts
3. **Optimize Caching**: Add Playwright browser cache
4. **Add Monitoring**: Integrate application monitoring
5. **Set Up Environments**: Configure staging/production environments

---

**Maintained By**: DevOps Team
**Last Updated**: December 30, 2025
**Version**: 1.0.0