---
name: mosaic-gitea
description: Interact with Gitea repositories on git.mosaicstack.dev — create/merge/close PRs, manage issues, milestones, and CI queue waits. Use when working with Mosaic Stack git repos. Wraps scripts in ~/.config/mosaic/tools/git/. Works on both Gitea and GitHub (auto-detected via detect-platform.sh).
---

# mosaic-gitea

Git operations via Mosaic wrapper scripts. Platform-aware (Gitea or GitHub).

## Setup

Scripts auto-detect platform from git remote. Run from inside the repo directory.

Credentials come from the framework credentials loader (never from a shared env
file):

```bash
source ~/.config/mosaic/tools/_lib/credentials.sh
load_credentials gitea-mosaicstack
# Exports: GITEA_TOKEN, GITEA_URL
```

## Script Reference

All scripts in `~/.config/mosaic/tools/git/`.

### Pull Requests

| Script           | Purpose                 | Key flags                                                |
| ---------------- | ----------------------- | -------------------------------------------------------- |
| `pr-create.sh`   | Create a PR             | `-t "Title" [-b "Body"] [-B base] [-H head] [-i issue#]` |
| `pr-list.sh`     | List open PRs           | `[-s state]`                                             |
| `pr-view.sh`     | View PR details         | `-n <pr#>`                                               |
| `pr-merge.sh`    | Squash-merge a PR       | `-n <pr#> [-d]` (delete branch)                          |
| `pr-close.sh`    | Close a PR              | `-n <pr#>`                                               |
| `pr-diff.sh`     | Show PR diff            | `-n <pr#>`                                               |
| `pr-review.sh`   | Submit a review         | `-n <pr#> [-a approve\|request-changes]`                 |
| `pr-ci-wait.sh`  | Wait for CI on PR       | `-n <pr#>`                                               |
| `pr-metadata.sh` | Get PR metadata as JSON | `-n <pr#>`                                               |

### Issues

| Script             | Purpose         | Key flags                                           |
| ------------------ | --------------- | --------------------------------------------------- |
| `issue-create.sh`  | Create an issue | `-t "Title" [-b "Body"] [-l labels] [-m milestone]` |
| `issue-list.sh`    | List issues     | `[-s state] [-l label]`                             |
| `issue-view.sh`    | View issue      | `-n <issue#>`                                       |
| `issue-close.sh`   | Close issue     | `-n <issue#>`                                       |
| `issue-comment.sh` | Add comment     | `-n <issue#> -c "Comment"`                          |
| `issue-assign.sh`  | Assign issue    | `-n <issue#> -u username`                           |
| `issue-edit.sh`    | Edit issue      | `-n <issue#> [-t title] [-b body]`                  |

### Milestones

| Script                | Purpose          | Key flags                    |
| --------------------- | ---------------- | ---------------------------- |
| `milestone-create.sh` | Create milestone | `-t "Title" [-d "due date"]` |
| `milestone-list.sh`   | List milestones  | —                            |
| `milestone-close.sh`  | Close milestone  | `-n <number>`                |

### CI / Queue

| Script               | Purpose                | Key flags                   |
| -------------------- | ---------------------- | --------------------------- |
| `ci-queue-wait.sh`   | Wait for CI queue slot | `[-t timeout] [-B branch]`  |
| `detect-platform.sh` | Detect git platform    | outputs `gitea` or `github` |

## Common Workflows

**Create PR from current branch:**

```bash
cd ~/src/<repo>
~/.config/mosaic/tools/git/pr-create.sh -t "feat: my feature" -b "Description" -i <issue#>
```

**Merge a PR (squash, with CI queue guard):**

```bash
cd ~/src/<repo>
~/.config/mosaic/tools/git/pr-merge.sh -n <pr#> -d
```

Branch protection is a gate, not an obstacle: if it blocks a merge, fix the cause —
a failing check, a moved head, or a missing review. Never bypass it with a raw
API call, a shared credential, or `force_merge`. Exceptional cases go to the
operator or the coordinating seat, still merged through the wrapper.

## Notes

- Mosaic policy: squash merges only, targeting `main`
- Gitea SSH: `git@git.mosaicstack.dev` → resolves via `~/.ssh/config` to the Gitea host's SSH port (e.g. `gitea.example.internal:2222`)
- Workers push branches and open PRs but **never merge** — orchestrator handles merges