492 lines
14 KiB
Markdown
492 lines
14 KiB
Markdown
# 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
|
|
|
|
|
|
|
|
```
|
|
|
|
## 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
|