littleshop/CI_CD_MIGRATION_GITEA.md

CI/CD Migration: GitLab → Gitea Actions

Date: November 14, 2025 Status: ✅ Complete

Overview

Successfully migrated from GitLab CI/CD to Gitea Actions for the LittleShop project.

Changes Made

1. Removed GitLab CI/CD Configuration

• ❌ Deleted: .gitlab-ci.yml (main project)
• ❌ Deleted: TeleBot/.gitlab-ci.yml (TeleBot subproject)

2. Created Gitea Actions Workflows

• ✅ Created: .gitea/workflows/build-and-deploy.yml - Main CI/CD pipeline
• ✅ Created: .gitea/workflows/rollback.yml - Manual rollback workflow
• ✅ Created: .gitea/workflows/README.md - Comprehensive documentation

3. Updated Git Remote

• ✅ Fetch URL: https://70ec152b27ee12d8a2cfb7241df5735351df72cd@git.silverlabs.uk/Jamie/littleshop.git
• ✅ Push URL: https://70ec152b27ee12d8a2cfb7241df5735351df72cd@git.silverlabs.uk/Jamie/littleshop.git

Workflow Features

Build and Deploy Workflow

Triggers:

• Push to main → Auto-deploy to production
• Push to development → Auto-deploy to development
• Push tags (v*) → Tagged release
• Manual trigger via UI

Jobs:

1. build-littleshop - Builds LittleShop Docker image
2. build-telebot - Builds TeleBot Docker image
3. deploy-production - Deploys to production VPS (requires both build jobs)
4. deploy-development - Deploys to development environment

Key Features:

• Parallel Docker builds for faster CI
• Artifact-based image transfer between jobs
• Automatic database migration application
• Health check validation
• Comprehensive deployment logging
• SSH-based VPS deployment

Rollback Workflow

Trigger: Manual only

Features:

• Choose environment (production/development)
• Specify version or rollback to previous
• Automatic health checks after rollback

Required Configuration

Repository Secrets (Gitea)

Navigate to: Repository → Settings → Secrets

Add the following secrets:

VPS_HOST: srv1002428.hstgr.cloud
VPS_PORT: 2255
VPS_USER: sysadmin
VPS_SSH_KEY: <SSH private key>

Environment Configuration

Navigate to: Repository → Settings → Environments

Production Environment

• Name: production
• URL: https://admin.dark.side
• Protection: Require approval (optional)

Development Environment

• Name: development
• URL:

Migration Benefits

✅ Advantages Over GitLab CI/CD

1. Native Integration: First-class support in Gitea UI
2. GitHub Actions Syntax: Industry-standard workflow format
3. Better Artifact Handling: Native artifact storage in Gitea
4. Cleaner Workflow UI: Better visualization in Gitea Actions tab
5. Environment Management: Built-in environment protection rules
6. Manual Triggers: Easy workflow_dispatch for manual runs

🔄 No Changes Required

The following remain unchanged:

• ✅ VPS deployment scripts (identical logic)
• ✅ Docker network configuration
• ✅ Database migration process
• ✅ Health check endpoints
• ✅ Container names and ports
• ✅ Nginx reverse proxy setup

Deployment Architecture

┌────────────────────────────────────────────┐
│          Gitea Actions Runner              │
│                                            │
│  ┌─────────────┐   ┌─────────────┐        │
│  │  LittleShop │   │   TeleBot   │        │
│  │    Build    │   │    Build    │        │
│  └──────┬──────┘   └──────┬──────┘        │
│         │                 │                │
│         └────────┬────────┘                │
│                  ▼                         │
│         ┌────────────────┐                 │
│         │Upload Artifacts│                 │
│         └────────┬───────┘                 │
└──────────────────┼────────────────────────┘
                   │ SSH Transfer
                   ▼
┌─────────────────────────────────────────────┐
│        Production VPS (Hostinger)           │
│                                             │
│  ┌────────────────────────────────────────┐ │
│  │ Docker Registry (localhost:5000)       │ │
│  │ - littleshop:latest, littleshop:<sha> │ │
│  │ - telebot:latest, telebot:<sha>       │ │
│  └────────────────────────────────────────┘ │
│                                             │
│  ┌─────────────┐  ┌─────────────┐          │
│  │ LittleShop  │  │  TeleBot    │          │
│  │ Container   │  │  Container  │          │
│  │ Port: 5100  │  │  Port: 5010 │          │
│  └──────┬──────┘  └──────┬──────┘          │
│         │                │                 │
│  ┌──────┴────────────────┴────────┐        │
│  │  Docker Networks:              │        │
│  │  - littleshop_littleshop-      │        │
│  │    network                     │        │
│  │  - silverpay_silverpay-        │        │
│  │    network                     │        │
│  └────────────────────────────────┘        │
│                                             │
│  ┌────────────────────────────────┐        │
│  │  Nginx Proxy Manager           │        │
│  │  https://admin.dark.side       │        │
│  └────────────────────────────────┘        │
└─────────────────────────────────────────────┘

Testing the Migration

1. Verify Gitea Actions Runner

Ensure your Gitea instance has Actions enabled:

# Check Gitea configuration
# In app.ini or via Gitea admin panel
[actions]
ENABLED = true

2. Test Build Workflow

Push to a test branch to trigger workflow:

git checkout -b test-gitea-actions
git add .gitea/
git commit -m "feat: Migrate to Gitea Actions"
git push origin test-gitea-actions

Check Gitea UI: Repository → Actions → Workflows

3. Monitor First Deployment

Watch the deployment progress:

1. Navigate to Gitea Actions tab
2. Select the running workflow
3. Monitor each job's logs in real-time
4. Verify health checks pass

Rollback Plan

If issues occur with Gitea Actions:

Option 1: Restore GitLab CI/CD (Emergency)

# Restore .gitlab-ci.yml from Git history
git checkout HEAD~1 -- .gitlab-ci.yml TeleBot/.gitlab-ci.yml
git add .gitlab-ci.yml TeleBot/.gitlab-ci.yml
git commit -m "Rollback to GitLab CI/CD"

Option 2: Manual Deployment

# Connect to VPS
ssh -p 2255 sysadmin@srv1002428.hstgr.cloud

# Manual deployment
cd /opt/littleshop
docker-compose down
docker-compose pull
docker-compose up -d

Next Steps

1. Configure Repository Secrets ⏳

• Add VPS_HOST to Gitea repository secrets
• Add VPS_PORT to Gitea repository secrets
• Add VPS_USER to Gitea repository secrets
• Add VPS_SSH_KEY to Gitea repository secrets

2. Configure Environments ⏳

• Create production environment in Gitea
• Set production URL: https://admin.dark.side
• Create development environment (optional)

3. Test Deployment ⏳

• Push to development branch for test deployment
• Verify build jobs complete successfully
• Verify deployment completes with health checks
• Test rollback workflow manually

4. Deploy to Production ⏳

• Merge security fixes to main branch
• Monitor automated production deployment
• Verify application health after deployment

Troubleshooting

Issue: "Actions disabled for this repository"

Solution: Enable Actions in Gitea repository settings or instance configuration.

# In Gitea app.ini
[actions]
ENABLED = true
DEFAULT_ACTIONS_URL = https://github.com  # For using GitHub marketplace actions

Issue: "No runners available"

Solution: Register a Gitea Actions runner.

# Download act_runner
wget https://dl.gitea.com/act_runner/latest/act_runner-linux-amd64
chmod +x act_runner-linux-amd64

# Register runner with Gitea
./act_runner-linux-amd64 register --instance https://git.silverlabs.uk --token <runner-token>

# Run as service
./act_runner-linux-amd64 daemon

Issue: "Secret not found"

Solution: Verify secrets are set correctly in repository settings.

Navigate to: Repository → Settings → Secrets and add missing secrets.

Documentation

• Workflow Documentation: .gitea/workflows/README.md
• Build Workflow: .gitea/workflows/build-and-deploy.yml
• Rollback Workflow: .gitea/workflows/rollback.yml

References

• Gitea Actions Documentation
• GitHub Actions Syntax
• Docker Build Push Action

---

Migration completed successfully! 🎉

All GitLab CI/CD functionality has been replicated in Gitea Actions with improved workflow management and native Gitea integration.