glyphdiff.com/frontend-svelte
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d4e2885ae081ea3982c39c4eb9b015b487919465
frontend-svelte/CICD.md
Ilia Mashkov 603529fd3f fix: format
2025-12-30 13:10:42 +03:00

14 KiB
Raw Blame History

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

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:

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:

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:

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

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

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

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

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

    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

Status Badges

Add to your README.md:

![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

Reference in New Issue View Git Blame Copy Permalink