pantry-app/pantry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ci: Add Gitea Actions workflows and CI/CD documentation
Some checks failed
Deploy to Coolify / Code Quality (push) Has been cancelled
Details
Deploy to Coolify / Run Tests (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Development (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Production (push) Has been cancelled
Details
Deploy to Coolify / Deploy to Test (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Claw
2026-02-08 20:05:04 +00:00
parent 19874c0b2c
commit f3ec382124
4 changed files with 870 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

358
docs/BRANCHING.md Normal file
View File

@@ -0,0 +1,358 @@
# Pantry - Branching Strategy
## 🌿 Branch Structure
```
main (production)
↑
└── develop (development)
↑
├── feature/barcode-scanner
├── feature/tag-system
├── fix/quantity-bug
└── chore/update-deps
```
---
## 📋 Branch Types
### `main` - Production
- **Purpose:** Production-ready code
- **Protection:** Require PR approval
- **Deploy:** Auto-deploy to production on push
- **Stability:** Must always be stable
**Rules:**
- Never commit directly
- Only merge from `develop` via release PR
- All merges must pass CI/CD checks
### `develop` - Development
- **Purpose:** Integration branch for features
- **Protection:** Require PR approval (optional)
- **Deploy:** Auto-deploy to dev environment on push
- **Stability:** Should be stable, but can have minor issues
**Rules:**
- Never commit directly (except hotfixes)
- Merge features via PR
- Keep in sync with `main` regularly
### `feature/*` - Features
- **Purpose:** New features or enhancements
- **Naming:** `feature/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`
**Examples:**
- `feature/barcode-scanner`
- `feature/tag-management`
- `feature/unit-conversions`
### `fix/*` - Bug Fixes
- **Purpose:** Fix bugs in `develop`
- **Naming:** `fix/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`
**Examples:**
- `fix/quantity-validation`
- `fix/tag-duplication`
### `hotfix/*` - Production Hotfixes
- **Purpose:** Critical fixes for production
- **Naming:** `hotfix/short-description`
- **Base:** Branch from `main`
- **Merge:** PR to both `main` AND `develop`
**Examples:**
- `hotfix/auth-bypass`
- `hotfix/data-corruption`
**Process:**
```bash
git checkout main
git pull
git checkout -b hotfix/critical-bug
# Fix bug
git push origin hotfix/critical-bug
# Create PR to main (deploy immediately)
# Create second PR to develop (keep in sync)
```
### `release/*` - Releases
- **Purpose:** Prepare for production release
- **Naming:** `release/v0.1.0`
- **Base:** Branch from `develop`
- **Merge:** PR to `main` (then tag)
**Process:**
```bash
git checkout develop
git pull
git checkout -b release/v0.1.0
# Update version, changelog, docs
git push origin release/v0.1.0
# Create PR to main
# After merge, tag main with v0.1.0
```
### `chore/*` - Maintenance
- **Purpose:** Dependencies, configs, tooling
- **Naming:** `chore/short-description`
- **Base:** Branch from `develop`
- **Merge:** PR to `develop`
**Examples:**
- `chore/update-nuxt`
- `chore/eslint-config`
- `chore/ci-improvements`
---
## 🔄 Workflow Examples
### Adding a Feature
```bash
# 1. Start from develop
git checkout develop
git pull origin develop
# 2. Create feature branch
git checkout -b feature/barcode-scanner
# 3. Work on feature
# ... make changes ...
# 4. Commit regularly
git add .
git commit -m "feat: Add barcode detection logic"
# 5. Push to remote
git push origin feature/barcode-scanner
# 6. Create PR to develop on Gitea
# Review → Merge → Auto-deploys to dev
```
### Releasing to Production
```bash
# 1. Ensure develop is stable
git checkout develop
git pull origin develop
# 2. Create release branch
git checkout -b release/v0.1.0
# 3. Update version and changelog
# Edit package.json, CHANGELOG.md
# 4. Commit and push
git commit -am "chore: Prepare v0.1.0 release"
git push origin release/v0.1.0
# 5. Create PR to main
# Review → Merge → Auto-deploys to production
# 6. Tag the release
git checkout main
git pull origin main
git tag -a v0.1.0 -m "Release v0.1.0"
git push origin v0.1.0
# 7. Merge back to develop (keep in sync)
git checkout develop
git merge main
git push origin develop
```
### Hotfix Production Issue
```bash
# 1. Branch from main
git checkout main
git pull origin main
git checkout -b hotfix/auth-bypass
# 2. Fix the issue
# ... fix ...
# 3. Commit and push
git commit -am "fix: Patch authentication bypass"
git push origin hotfix/auth-bypass
# 4. Create PR to main
# Urgent review → Merge → Immediate deploy
# 5. Also PR to develop (keep in sync)
git checkout develop
git pull origin develop
git checkout -b hotfix/auth-bypass-to-develop
git merge hotfix/auth-bypass
git push origin hotfix/auth-bypass-to-develop
# Create second PR to develop
```
---
## 📝 Commit Message Convention
Follow [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Types
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, no logic change)
- `refactor`: Code refactoring
- `test`: Adding/updating tests
- `chore`: Maintenance (deps, configs)
- `perf`: Performance improvement
### Examples
```bash
feat(scan): Add barcode scanner component
fix(inventory): Prevent negative quantities
docs(api): Update product lookup examples
chore(deps): Upgrade Nuxt to 4.1.2
refactor(tags): Simplify tag picker logic
test(units): Add conversion edge cases
```
---
## 🔒 Branch Protection Rules
### `main` (Production)
- ✅ Require pull request before merging
- ✅ Require status checks to pass
- ✅ Require review from code owner (1+)
- ✅ Dismiss stale approvals
- ❌ Allow force push
- ❌ Allow deletions
### `develop` (Development)
- ✅ Require pull request before merging (optional)
- ✅ Require status checks to pass
- ⚠️ Require review (recommended, not enforced)
- ❌ Allow force push
- ❌ Allow deletions
**Configure in Gitea:**
Repository → Settings → Branches → Add rule
---
## 🎯 Best Practices
### Keep Branches Short-Lived
- Feature branches: 1-3 days max
- Merge frequently to avoid conflicts
- Delete after merge
### Sync with Develop Regularly
```bash
# While on feature branch
git checkout feature/my-feature
git fetch origin
git merge origin/develop
# Resolve conflicts if any
```
### Clean Commit History
```bash
# Interactive rebase before PR (optional)
git rebase -i develop
# Squash WIP commits into logical commits
```
### Tag Releases
```bash
# After merging release to main
git checkout main
git pull
git tag -a v0.1.0 -m "MVP Release - Week 6"
git push origin v0.1.0
```
---
## 🚫 Anti-Patterns (Don't Do This)
❌ **Commit directly to `main`**
- Always use PR workflow
❌ **Long-lived feature branches**
- Break into smaller features
- Merge incrementally
❌ **Merge without review**
- At least one other person should review
❌ **Push broken code to `develop`**
- Test locally first
- CI checks should pass
❌ **Forget to sync hotfix to `develop`**
- Hotfixes must go to both branches
---
## 📊 Branch Lifecycle
```
feature/barcode-scanner
Created: 2026-02-10
Author: Jean-Luc
Status: In Progress
PRs: #15 (to develop)
↓ (PR merged)
Merged to develop: 2026-02-12
Deployed to dev: ✅
Deleted: 2026-02-12
```
**Keep branches clean:**
```bash
# List merged branches
git branch --merged develop
# Delete merged local branches
git branch -d feature/barcode-scanner
# Delete merged remote branches
git push origin --delete feature/barcode-scanner
```
---
**Summary:** Keep it simple. Feature → PR → Develop → Test → Release → Main → Production. Always review, always test, never break `main`.

311
docs/CI_CD.md Normal file
View 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
[![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