94 lines
4.4 KiB
Markdown
94 lines
4.4 KiB
Markdown
---
|
|
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: `[email protected]` → 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
|