Team workflow

Tools and URLs

Tool	Role	URL
Plane	Issues, Kanban, sprints	https://pm.rafaelgonzalezalbes.com
Forgejo	Git repos, PRs	https://git.rafaelgonzalezalbes.com
Woodpecker	CI/CD pipelines	https://ci.rafaelgonzalezalbes.com

Issue workflow (Plane)

1. Create issue in Plane — use project key prefix (e.g. BIOS-12)
2. Add to Cycle (sprint) when planning
3. Move card on Kanban: Backlog → In Progress → Review → Done
4. Close issue when deployed — reference in commit: fixes BIOS-12

Issue types

• Bug — something broken in production or dev
• Story — user-facing feature
• Task — technical work (infra, refactor, docs)

Git workflow (Forgejo)

Branch naming

feature/BIOS-42-short-description
bugfix/BIOS-51-fix-scanner-crash
hotfix/BIOS-99-urgent-patch

Pull request rules

1. One issue per branch when possible
2. PR title: [BIOS-42] Add barcode validation
3. Require 1 approval before merge
4. CI must pass (Woodpecker green) before merge
5. Squash merge to main for clean history

Commit messages

BIOS-42: validate EAN-13 checksum before lookup

fixes BIOS-42

CI/CD pipeline (Woodpecker)

On every push / PR

Step	What it does
install	npm ci, build mcp-server
test	Run frontend + mcp-server tests
build	npm run build (Vite production bundle)
notify-ci-*	Post CI status comment to linked Plane issue (BIOS-N in branch)

On merge to main only

Step	Target	Method
deploy-frontend	Shared web hosting	SFTP upload of dist/
build-push-backend	Forgejo container registry	Docker image
deploy-backend	VPS	SSH + docker compose up -d

Required Woodpecker secrets (per repo)

Secret	Used for
ftp_host	Web hosting hostname
ftp_user	FTP/SFTP username
ftp_pass	FTP/SFTP password
frontend_remote_path	Remote directory
docker_registry_user	Forgejo username
docker_registry_token	Forgejo personal access token (packages:write)
ssh_host	VPS IP or hostname
ssh_user	Deploy user on VPS
ssh_key	Private SSH key for deploy
plane_api_key	Plane CI notifications

Mark the repository as Trusted in Woodpecker to use deployment secrets.

Deployment targets

• Frontend (React/Vite) → IONOS via SFTP
• Backend (mcp-server) → VPS Docker

New project checklist

1. Run bash scripts/onboard-project.sh (see Onboard project)
2. Create Forgejo repo under org
3. Copy Woodpecker template + notify steps
4. Push main, verify pipeline + Plane link

Roles

Role	Plane	Forgejo	Woodpecker
Admin	Workspace admin	Org owner	Server admin
Developer	Member	Write access	Activate own repos
Reviewer	Member	Write + approve PRs	View pipelines

Getting help

• Platform docs: https://docs.rafaelgonzalezalbes.com
• Backups: bash scripts/backup.sh (daily cron recommended)