pantry/docs/deployment/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:**
```bash
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

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

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

```bash
# 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:**
```bash
# 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:**
```bash
# In Gitea UI:
# Repository → Settings → Secrets → Actions
# Ensure COOLIFY_WEBHOOK_* secrets exist
```

---

## 📊 Workflow Status Badges

Add to `README.md`:

```markdown
[![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](https://docs.gitea.com/usage/actions/overview)
- [Coolify Webhooks](https://coolify.io/docs/knowledge-base/git/github/webhooks)
- [GitHub Actions Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions) (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