---
name: gitea-push
description: Commits and pushes code to the homelab Gitea server using conventional commit format. Use this skill when finishing any homelab, MCP builder, or BigMind work that needs to be saved to the homelab Gitea at http://192.168.188.119:30008/.
---

# Gitea Push

## When to use
- Finished a homelab change and need to commit + push
- Finished an MCP server build or update
- BigMind feature complete
- Wiki pages were added or updated (always deploy wiki after docs changes)

## When NOT to use
- ADP/Paisy work — that goes to the corporate Bitbucket, not homelab Gitea
- Uncommitted work that isn't ready (don't push broken state)

## Inputs required
- A description of what changed (for commit message)
- The type of change (see conventional commit types below)
- The scope (e.g., `mcp-webscraper`, `bigmind`, `homelab-docker`)
- The working branch name (or "main" — but you should NOT be on main)

## Branch Convention

**Never commit directly to `main`.** Every piece of work lives on its own branch.

Format: `type/scope/short-description`

| Type | When |
|------|------|
| `feat` | New feature, server, or tool |
| `fix` | Bug fix |
| `docs` | Docs, plans, strategy files |
| `chore` | Refactoring, config, CI, build |
| `spike` | Experimental / throwaway exploration |

Scope = the affected project area: `bigmind` · `webscraper` · `cannamanage` · `workshop` · `roo` · `plans`

Examples:
- `feat/bigmind/people-contacts`
- `fix/bigmind/health-check-bugs`
- `docs/plans/cannamanage-strategy`
- `chore/workshop/monorepo-reorganize`

## Workflow

1. **Check current branch — branch guard (MANDATORY):**
   ```bash
   git branch --show-current
   ```
   - If already on a correct feature branch → continue to step 2
   - If on `main` → **STOP. Create a branch first:**
     ```bash
     git checkout -b feat/scope/short-description
     ```
   - Never commit to `main`. Not even for "tiny fixes".

2. **Check status:**
   ```bash
   git status
   git diff --stat
   ```

3. **Stage changes:**
   ```bash
   git add -A
   # or selectively: git add path/to/file
   ```

4. **Write conventional commit message:**

   Format: `type(scope): short description`

   | Type | When |
   |------|------|
   | `feat` | New feature or tool |
   | `fix` | Bug fix |
   | `refactor` | Code restructure, no behavior change |
   | `test` | Adding or updating tests |
   | `docs` | Documentation only |
   | `chore` | Build, dependencies, config |
   | `style` | Formatting, no logic change |

   Examples:
   - `feat(mcp-webscraper): add ssl cert fallback with certifi`
   - `fix(bigmind): resolve FTS5 reserved-word collision`
   - `chore(homelab): update docker-compose for gitea upgrade`

5. **Commit:**
   ```bash
   git commit -m "type(scope): description"
   ```

6. **Push branch to Gitea:**
   ```bash
   git push origin feat/scope/short-description
   ```
   Gitea URL: `http://192.168.188.119:30008/pplate/pi_mcps.git`

7. **Merge to main when done:**
   ```bash
   git checkout main
   git merge --no-ff feat/scope/short-description
   git push origin main
   ```
   Or use the Gitea UI merge button if you want the paper trail.

8. **Store fact in BigMind:**
   ```
   memory_store_fact("codebase", "Committed: type(scope) — brief description of what changed")
   ```

## Troubleshooting
- **Auth error:** PAT stored in BigMind (fact: Gitea personal access token). Check `~/.netrc` or `~/.gitconfig`
- **Push rejected:** Pull first → `git pull --rebase origin main`
- **Wrong remote:** `git remote -v` to verify Gitea URL is set correctly
- **Accidentally committed to main:** `git branch feat/scope/name`, `git reset HEAD~1`, `git checkout feat/scope/name`, re-commit