pantry/docs/CI_CD.md

Pantry - CI/CD Pipeline

Version: 1.0
Last Updated: 2026-02-08

---

🔄 Overview

Pantry uses Gitea Actions for CI/CD, automatically deploying to Coolify on push.

Workflow Strategy

Feature Branch → PR → Code Review → Merge → Auto-Deploy
      ↓
  PR Checks
   (no deploy)

Environments:

• Development (develop branch) → Auto-deploy to dev.pantry
• Production (main branch) → Auto-deploy to pantry
• Test (manual trigger) → On-demand testing

---

📋 Workflows

1. deploy.yml - Main Deployment Pipeline

Triggers:

• Push to main → Deploy to production
• Push to develop → Deploy to development
• Pull requests → Run quality checks only

Jobs:

1. quality-check - Runs on all pushes/PRs

   • Type checking
   • Linting
   • Code formatting validation

2. test - Runs unit tests

   • Unit tests (Vitest)
   • Integration tests (future)

3. deploy-dev - Development deployment

   • Trigger: Push to develop
   • Target: Coolify dev environment
   • Auto-deploy

4. deploy-prod - Production deployment

   • Trigger: Push to main
   • Target: Coolify production environment
   • Auto-deploy

5. deploy-test - Test deployment (optional)

   • Trigger: Manual (workflow_dispatch)
   • Target: Coolify test environment

2. pr-checks.yml - Pull Request Validation

Triggers:

• Pull requests to main or develop

Jobs:

• Type checking
• Linting
• Tests
• Migration validation
• PR summary generation

---

🔐 Required Secrets

Configure these in Gitea Repository Settings → Secrets:

Coolify Webhook URLs

1. COOLIFY_WEBHOOK_DEV

   • Coolify webhook URL for dev environment
   • Format: https://coolify.jeanlucmakiola.de/api/v1/deploy/webhooks/{uuid}

2. COOLIFY_WEBHOOK_PROD

   • Coolify webhook URL for production environment
   • Same format as above

3. COOLIFY_WEBHOOK_TEST (optional)

   • Coolify webhook URL for test environment

How to Get Webhook URLs

Via Coolify UI:

1. Go to Coolify → Projects → Pantry
2. Select environment (dev/prod/test)
3. Click on the resource (application)
4. Go to "Webhooks" or "Deploy" tab
5. Copy webhook URL

Via Coolify API:

source ~/.openclaw/workspace/coolify-helpers.sh
COOLIFY_URL=$(grep COOLIFY_URL ~/.coolify-credentials | cut -d= -f2)
COOLIFY_TOKEN=$(grep COOLIFY_TOKEN ~/.coolify-credentials | cut -d= -f2)

# Get application UUID (once created)
curl -s -H "Authorization: Bearer $COOLIFY_TOKEN" \
  "${COOLIFY_URL}/api/v1/applications" | jq '.[] | select(.name | contains("pantry"))'

# Webhook format:
# ${COOLIFY_URL}/api/v1/deploy/webhooks/{application_uuid}

---

🚀 Deployment Flow

Development Workflow

# 1. Create feature branch
git checkout -b feature/barcode-scanner

# 2. Make changes
# ... code ...

# 3. Commit and push
git add .
git commit -m "feat: Add barcode scanner component"
git push origin feature/barcode-scanner

# 4. Create PR to 'develop'
# → PR checks run automatically

# 5. Merge PR
# → Auto-deploys to dev environment

Production Release

# 1. Ensure develop is stable
git checkout develop
git pull

# 2. Create release PR to main
git checkout -b release/v0.1.0

# 3. Update version, changelog
# ... updates ...

# 4. Push and create PR to main
git push origin release/v0.1.0
# → PR checks run

# 5. Merge to main
# → Auto-deploys to production

---

🏗️ Coolify Setup (Per Environment)

Prerequisites

Each environment needs:

1. Supabase service (already configured for dev)
2. Pantry app resource (to be created)

Creating App Resource in Coolify

For each environment (dev/prod/test):

1. Go to Coolify → Projects → Pantry → [Environment]

2. Add New Resource:

   • Type: Application
   • Source: Git Repository

3. Configure Git:

   • Repository: https://gitea.jeanlucmakiola.de/pantry-app/pantry.git
   • Branch:
     • Dev: develop
     • Prod: main
     • Test: develop (or specific branch)

4. Build Configuration:

   • Build Pack: Nixpacks or Dockerfile
   • Dockerfile Path: app/Dockerfile (when created)
   • Build Command: bun install && bun run build
   • Start Command: bun run start

5. Environment Variables:

   • Import from .env.development or .env.production
   • Link to Supabase service environment

6. Domain:

   • Dev: pantry-dev.jeanlucmakiola.de
   • Prod: pantry.jeanlucmakiola.de
   • Test: pantry-test.jeanlucmakiola.de

7. Enable Webhook:

   • Go to resource → Webhooks
   • Copy webhook URL
   • Add to Gitea secrets

---

🔍 Monitoring Deployments

Via Gitea

• Actions Tab in repository
• View workflow runs
• Check logs for each job

Via Coolify

• Resources → Select environment
• Deployments tab shows history
• Logs show build/runtime output

Manual Trigger (Emergency Deploy)

# Via Gitea Actions UI
# Repository → Actions → deploy.yml → Run workflow

# Or via webhook directly
curl -X POST "https://coolify.jeanlucmakiola.de/api/v1/deploy/webhooks/{uuid}"

---

🐛 Troubleshooting

Workflow Not Running

Check:

• Gitea Actions is enabled (repo settings)
• .gitea/workflows/ directory exists
• YAML syntax is valid

Enable Gitea Actions:

# If self-hosted Gitea instance
# Check Gitea admin panel → Actions → Enabled

Deployment Failed

Check:

1. Gitea Actions logs - See which step failed
2. Coolify deployment logs - Build/runtime errors
3. Environment variables - Missing/incorrect values
4. Webhook URL - Correct and accessible

Secrets Not Working

Verify:

# In Gitea UI:
# Repository → Settings → Secrets → Actions
# Ensure COOLIFY_WEBHOOK_* secrets exist

---

📊 Workflow Status Badges

Add to README.md:

[![Deploy](https://gitea.jeanlucmakiola.de/pantry-app/pantry/actions/workflows/deploy.yml/badge.svg)](https://gitea.jeanlucmakiola.de/pantry-app/pantry/actions)

---

🔮 Future Improvements

v0.2+

• E2E tests in pipeline (Playwright)
• Database migration validation
• Performance benchmarks
• Lighthouse CI (PWA scores)
• Automatic changelog generation
• Slack/Discord notifications

v0.3+

• Staging environment
• Blue-green deployments
• Rollback automation
• Database backup before migrations

---

📚 References

• Gitea Actions Docs
• Coolify Webhooks
• GitHub Actions Syntax (compatible with Gitea)

---

Next Steps:

1. Get Coolify webhook URLs for dev/prod
2. Add secrets to Gitea repository
3. Create Pantry app resources in Coolify
4. Test deployment pipeline