ci: Add Gitea Actions workflows and CI/CD documentation
Some checks failed
Deploy to Coolify / Code Quality (push) Has been cancelled
Deploy to Coolify / Run Tests (push) Has been cancelled
Deploy to Coolify / Deploy to Development (push) Has been cancelled
Deploy to Coolify / Deploy to Production (push) Has been cancelled
Deploy to Coolify / Deploy to Test (push) Has been cancelled
Some checks failed
Deploy to Coolify / Code Quality (push) Has been cancelled
Deploy to Coolify / Run Tests (push) Has been cancelled
Deploy to Coolify / Deploy to Development (push) Has been cancelled
Deploy to Coolify / Deploy to Production (push) Has been cancelled
Deploy to Coolify / Deploy to Test (push) Has been cancelled
This commit is contained in:
Claw
311
docs/CI_CD.md
Normal file
311
docs/CI_CD.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# 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
|
||||
[](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
|
||||
Reference in New Issue
Block a user