docs: trim repeated boilerplate in git, gitea, and bin skills
Finding 13: five blocks of near-identical wording were repeated across skills within a plugin — the gitea "resolve owner and repo" step (5 skills), the 404-masks-403 note (6 files), the manual pagination explanation (8 files), the git plugin's main/master force-push refusal (7 files, some with multiple internal restatements), and the bin skills' domain-glossary/ADR paragraph (5 skills). Tightened each instance in place — same meaning, fewer words — rather than extracting to a shared file, which ADR-0014's one-file-per-skill install constraint rules out. Left the three git skills' structured-result JSON shapes alone (coupled to the separate, out-of-scope git-orchestrate merge candidate, finding 19). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
This commit is contained in:
@@ -5,14 +5,14 @@ description: >
|
||||
broken, throwing, or failing, or says something got slow. Not filing or
|
||||
triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Diagnose
|
||||
|
||||
A discipline for hard bugs. Skip phases only when explicitly justified.
|
||||
|
||||
When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
|
||||
When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area.
|
||||
|
||||
## Phase 1 — Build a feedback loop
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
|
||||
failure -> `diagnose`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Improve Codebase Architecture
|
||||
@@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give
|
||||
|
||||
### 1. Explore
|
||||
|
||||
Read the project's domain glossary and any ADRs in the area you're touching first.
|
||||
Read the domain glossary and any ADRs in the area first.
|
||||
|
||||
Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: >
|
||||
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
|
||||
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Test-Driven Development
|
||||
@@ -49,7 +49,7 @@ RIGHT (vertical):
|
||||
|
||||
### 1. Planning
|
||||
|
||||
When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
|
||||
When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area.
|
||||
|
||||
Before writing any code:
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: >
|
||||
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
|
||||
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Triage
|
||||
@@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
|
||||
|
||||
## Triage a specific issue
|
||||
|
||||
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
|
||||
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
|
||||
|
||||
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ name: zoom-out
|
||||
description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
|
||||
disable-model-invocation: true
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.
|
||||
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary.
|
||||
|
||||
@@ -5,14 +5,14 @@ description: >
|
||||
broken, throwing, or failing, or says something got slow. Not filing or
|
||||
triaging a reported bug -> `triage`. Not test-first feature work -> `tdd`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Diagnose
|
||||
|
||||
A discipline for hard bugs. Skip phases only when explicitly justified.
|
||||
|
||||
When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
|
||||
When exploring the codebase, use the domain glossary for a clear mental model of the relevant modules, and check ADRs in the area.
|
||||
|
||||
## Phase 1 — Build a feedback loop
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@ description: >
|
||||
into deep ones, informed by `CONTEXT.md` and `docs/adr/`. Not debugging a
|
||||
failure -> `diagnose`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Improve Codebase Architecture
|
||||
@@ -41,7 +41,7 @@ This skill is _informed_ by the project's domain model. The domain language give
|
||||
|
||||
### 1. Explore
|
||||
|
||||
Read the project's domain glossary and any ADRs in the area you're touching first.
|
||||
Read the domain glossary and any ADRs in the area first.
|
||||
|
||||
Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: >
|
||||
red-green-refactor loop, one behaviour at a time. Not diagnosing an existing
|
||||
bug -> `diagnose`. Not throwaway exploratory code -> `prototype`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Test-Driven Development
|
||||
@@ -49,7 +49,7 @@ RIGHT (vertical):
|
||||
|
||||
### 1. Planning
|
||||
|
||||
When exploring the codebase, use the project's domain glossary so that test names and interface vocabulary match the project's language, and respect ADRs in the area you're touching.
|
||||
When exploring the codebase, use the domain glossary so test names and interface vocabulary match the project's language, and respect ADRs in the area.
|
||||
|
||||
Before writing any code:
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ description: >
|
||||
tracker's triage states, or an issue prepared for an AFK agent. Not debugging
|
||||
the bug itself -> `diagnose`. Not fleshing out a design -> `grill-with-docs`.
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
# Triage
|
||||
@@ -65,7 +65,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
|
||||
|
||||
## Triage a specific issue
|
||||
|
||||
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
|
||||
1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
|
||||
|
||||
2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@ name: zoom-out
|
||||
description: Tell the agent to zoom out and give broader context or a higher-level perspective. Use when you're unfamiliar with a section of code or need to understand how it fits into the bigger picture.
|
||||
disable-model-invocation: true
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
---
|
||||
|
||||
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary vocabulary.
|
||||
I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary.
|
||||
|
||||
@@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the
|
||||
|
||||
When invoked, you:
|
||||
1. Parse the incoming workflow request (operation type, parameters, context overrides)
|
||||
2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
|
||||
2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
|
||||
3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes`
|
||||
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
|
||||
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
|
||||
|
||||
@@ -9,7 +9,7 @@ description: >
|
||||
Not a Gitea remote's branches -> `gitea-branches`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.3"
|
||||
version: "1.0.4"
|
||||
category: git
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
@@ -22,7 +22,7 @@ metadata:
|
||||
|
||||
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
|
||||
- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
|
||||
- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
|
||||
- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead.
|
||||
|
||||
## Step 1 — Determine the branching pattern
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
Not branch lifecycle -> `git-branches`.
|
||||
|
||||
metadata:
|
||||
version: "0.1.5"
|
||||
version: "0.1.6"
|
||||
category: git
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
@@ -22,7 +22,7 @@ allowed-tools: Bash
|
||||
## Gotchas
|
||||
|
||||
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here).
|
||||
- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it.
|
||||
- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it.
|
||||
- **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first.
|
||||
- **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.
|
||||
|
||||
|
||||
@@ -6,14 +6,14 @@ source_keys:
|
||||
|
||||
# Rewriting existing commits
|
||||
|
||||
Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead.
|
||||
Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why.
|
||||
|
||||
## Amend the last commit
|
||||
|
||||
1. Stage the new changes, or the changes that undo something.
|
||||
2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
|
||||
3. If the message should change, show the current one and prompt for the replacement.
|
||||
4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding.
|
||||
4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed.
|
||||
|
||||
## Fold a commit into an earlier one (autosquash — preferred)
|
||||
|
||||
@@ -50,9 +50,8 @@ date without a merge commit.
|
||||
4. `rtk git rebase <newbase>` — for example `rtk git rebase main`. Use
|
||||
`rtk git rebase --onto <newbase> <upstream> <branch>` to replay only the commits after
|
||||
`<upstream>`, which is how a branch started from the wrong base gets moved.
|
||||
5. The branch has now diverged from its remote. It needs
|
||||
`--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on
|
||||
`main`/`master` — refuse that and explain.
|
||||
5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`,
|
||||
never a bare `--force` — and never on `main`/`master`; refuse that and explain.
|
||||
|
||||
## Move the branch pointer back (`git reset`)
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ description: >
|
||||
Not submodule pointers -> `git-submodules`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.2"
|
||||
version: "1.0.3"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-remote-docs
|
||||
@@ -28,7 +28,7 @@ metadata:
|
||||
|
||||
## Step 1 — Clear the force-push gate
|
||||
|
||||
`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing.
|
||||
`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing.
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: git
|
||||
source_keys:
|
||||
- nvie-gitflow-post
|
||||
@@ -60,7 +60,7 @@ owns the request.
|
||||
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
|
||||
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
|
||||
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
|
||||
confirmations: never offer "Proceed?" for a force-push of `main` or `master`.
|
||||
confirmations — never offer "Proceed?" for a force-push of `main`/`master`.
|
||||
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
|
||||
inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
|
||||
destructive op the user approved in step 4.
|
||||
|
||||
@@ -40,7 +40,7 @@ Sub-skills carry their own local copies of these rules for humans who invoke the
|
||||
|
||||
When invoked, you:
|
||||
1. Parse the incoming workflow request (operation type, parameters, context overrides)
|
||||
2. Check safety gates: if the operation is destructive (force-push, branch deletion, rebase with history loss, force-checkout) and the request lacks explicit `confirm: true`, fail immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
|
||||
2. Check safety gates: a destructive operation (force-push, branch deletion, history-losing rebase, force-checkout) without `confirm: true` fails immediately with "requires explicit confirmation"; force-push to `main`/`master` is refused outright regardless of `confirm`
|
||||
3. Route to the appropriate domain skill: `git-commits`, `git-branches`, `git-history`, `git-submodules`, `git-worktrees`, `git-remotes`
|
||||
4. Manage session context: carry forward the current branch, workflow intent, and configuration, passing explicitly to each skill
|
||||
5. Handle error recovery: for recoverable failures (merge conflicts, push rejections, auth issues), attempt automatic recovery; if unrecoverable, fail gracefully with actionable diagnostics
|
||||
|
||||
@@ -9,7 +9,7 @@ description: >
|
||||
Not a Gitea remote's branches -> `gitea-branches`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.3"
|
||||
version: "1.0.4"
|
||||
category: git
|
||||
source_keys:
|
||||
- context7-git-htmldocs
|
||||
@@ -22,7 +22,7 @@ metadata:
|
||||
|
||||
- **Uncommitted changes abort a switch.** `git switch` refuses rather than clobbering conflicting local edits. Offer to stash and retry — forcing the checkout past it is how work disappears.
|
||||
- **A branch and a tag can carry the same name.** Detect it before acting — `git branch --list <name>` (bare, not `rtk`: rtk prints a phantom `* ` line even on no match, which reports every name as ambiguous) and `rtk git tag --list <name>`; output from both means the name is ambiguous. Prefer `git switch` over `git checkout`, and where a command accepts either ref, disambiguate with `refs/heads/<name>` or `refs/tags/<name>`.
|
||||
- **`main` and `master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming them is rejected even when the caller passes `confirm: true` — no flag makes the remote's history recoverable. Offer a new branch instead.
|
||||
- **`main`/`master` are a refusal, not a gate.** Force-pushing, force-deleting, or renaming either is rejected even with `confirm: true` — no flag recovers the remote's history. Offer a new branch instead.
|
||||
|
||||
## Step 1 — Determine the branching pattern
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
Not branch lifecycle -> `git-branches`.
|
||||
|
||||
metadata:
|
||||
version: "0.1.5"
|
||||
version: "0.1.6"
|
||||
category: git
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
@@ -22,7 +22,7 @@ allowed-tools: Bash
|
||||
## Gotchas
|
||||
|
||||
- **Run git as `rtk git <subcommand>`, never bare `git`** — org convention, in `&&` chains too, except where a skill's Gotchas name a specific bare-git case (interactive rebase here).
|
||||
- **Refuse to force-push `main`/`master`** — a rewrite leaves the branch diverged and the reflex is to force it back; safe only where nobody else has based work on it.
|
||||
- **Refuse to force-push `main`/`master`.** A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it.
|
||||
- **`reset --hard` is a confirmation gate, not a default.** It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first.
|
||||
- **Never add `--no-verify`** — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.
|
||||
|
||||
|
||||
@@ -6,14 +6,14 @@ source_keys:
|
||||
|
||||
# Rewriting existing commits
|
||||
|
||||
Every flow on this page rewrites history. None of them runs before the caller has explicitly approved it, and none is followed by a force-push to `main`/`master` — refuse that and explain why instead.
|
||||
Every flow here rewrites history. None runs without explicit approval, and none ends in a force-push to `main`/`master` — refuse that and explain why.
|
||||
|
||||
## Amend the last commit
|
||||
|
||||
1. Stage the new changes, or the changes that undo something.
|
||||
2. Run `rtk git commit --amend`, adding `--no-edit` when the message stays as it is.
|
||||
3. If the message should change, show the current one and prompt for the replacement.
|
||||
4. The branch has now diverged from its remote. Amending is safe only on a branch nobody else has based work on; on `main`/`master`, refuse the force-push and explain, rather than warning and proceeding.
|
||||
4. The branch has diverged from its remote. Amending is safe only where nobody else has based work on it; on `main`/`master`, refuse the force-push and explain rather than warn and proceed.
|
||||
|
||||
## Fold a commit into an earlier one (autosquash — preferred)
|
||||
|
||||
@@ -50,9 +50,8 @@ date without a merge commit.
|
||||
4. `rtk git rebase <newbase>` — for example `rtk git rebase main`. Use
|
||||
`rtk git rebase --onto <newbase> <upstream> <branch>` to replay only the commits after
|
||||
`<upstream>`, which is how a branch started from the wrong base gets moved.
|
||||
5. The branch has now diverged from its remote. It needs
|
||||
`--force-with-lease --force-if-includes` to push, never a bare `--force`, and never on
|
||||
`main`/`master` — refuse that and explain.
|
||||
5. The branch has diverged from its remote. Push needs `--force-with-lease --force-if-includes`,
|
||||
never a bare `--force` — and never on `main`/`master`; refuse that and explain.
|
||||
|
||||
## Move the branch pointer back (`git reset`)
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ description: >
|
||||
Not submodule pointers -> `git-submodules`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.2"
|
||||
version: "1.0.3"
|
||||
category: git
|
||||
source_keys:
|
||||
- git-scm-remote-docs
|
||||
@@ -28,7 +28,7 @@ metadata:
|
||||
|
||||
## Step 1 — Clear the force-push gate
|
||||
|
||||
`main` and `master` are a hard refusal: decline a force-push targeting either, whatever confirmation accompanies it, because no local approval can restore what the remote loses. On any other branch, `rtk git push --force` and `-f` run only after the caller passes `confirm: true` for that specific push — for a human caller, prompt instead of failing.
|
||||
`main`/`master` are a hard refusal: decline a force-push to either regardless of confirmation — no local approval restores what the remote loses. Elsewhere, `rtk git push --force`/`-f` run only after `confirm: true` for that specific push; for a human caller, prompt instead of failing.
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -8,7 +8,7 @@ description: >
|
||||
agent caller -> `git-orchestrate`. Not Gitea -> `gitea-workflow`.
|
||||
|
||||
metadata:
|
||||
version: "1.0.1"
|
||||
version: "1.0.2"
|
||||
category: git
|
||||
source_keys:
|
||||
- nvie-gitflow-post
|
||||
@@ -60,7 +60,7 @@ owns the request.
|
||||
4. **Gate destructive operations** — before force-push, branch deletion, rebase, or
|
||||
force-checkout, show what will happen and ask "Proceed?". Cancel gracefully if the user
|
||||
declines. Never supply the confirmation on the user's behalf. Some operations are refusals, not
|
||||
confirmations: never offer "Proceed?" for a force-push of `main` or `master`.
|
||||
confirmations — never offer "Proceed?" for a force-push of `main`/`master`.
|
||||
5. **Invoke the `git-orchestrate` agent** with `operation`, `parameters` (user-provided or
|
||||
inferred), `context` (step 3 plus the session context), and `confirm: true` only for a
|
||||
destructive op the user approved in step 4.
|
||||
|
||||
@@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing.
|
||||
- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`.
|
||||
- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing.
|
||||
- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`.
|
||||
- **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`.
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
Before any tool call, extract `owner` and `repo` from the git remote:
|
||||
Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -29,8 +29,7 @@ list_branches owner: <owner> repo: <repo>
|
||||
**Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the
|
||||
underlying commit data is available).
|
||||
|
||||
Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned
|
||||
count is less than `per_page`.
|
||||
Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`.
|
||||
|
||||
## `create_branch`
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a
|
||||
is not actually required for any of this domain's five tools.
|
||||
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
category: gitea
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
@@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first.
|
||||
- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing.
|
||||
- **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped.
|
||||
- **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage.
|
||||
|
||||
|
||||
@@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`.
|
||||
`get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk
|
||||
subdirectories in one call.
|
||||
|
||||
The response sets `truncated: true` when one page does not hold every entry. Page through with
|
||||
`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`.
|
||||
The response sets `truncated: true` when one page doesn't hold every entry — page with
|
||||
`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`.
|
||||
|
||||
## Neither listing is a SHA source for a write
|
||||
|
||||
@@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t
|
||||
|
||||
## A 404 that is really a 403
|
||||
|
||||
These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer
|
||||
an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A
|
||||
404 on a path you are confident about is a scope problem until proven otherwise — check the token's
|
||||
configured scopes before concluding the file or directory does not exist.
|
||||
These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the
|
||||
endpoint doesn't leak whether the resource exists. On a path you're confident about, check token
|
||||
scope before concluding it doesn't exist.
|
||||
|
||||
@@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.4"
|
||||
version: "0.1.5"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
@@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i
|
||||
- **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`).
|
||||
- **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels.
|
||||
- **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually.
|
||||
- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist.
|
||||
- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist.
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call:
|
||||
Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ list_issues owner: <owner> repo: <repo> state: "open" type: "issues"
|
||||
`updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`.
|
||||
Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those.
|
||||
|
||||
Paginate with `page`/`per_page` until the returned count is less than `per_page`.
|
||||
Paginate: `page`/`per_page`, stop once the count is below `per_page`.
|
||||
|
||||
## `issue_read`
|
||||
|
||||
|
||||
@@ -16,30 +16,30 @@ metadata:
|
||||
- gitea-mcp-slim-go
|
||||
- context7-websites-gitea
|
||||
- context7-gitea-tea-cli
|
||||
version: "0.1.5"
|
||||
version: "0.1.6"
|
||||
|
||||
allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`.
|
||||
- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title.
|
||||
- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label.
|
||||
- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first.
|
||||
- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title.
|
||||
- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one.
|
||||
|
||||
## Step 1 — Resolve owner, repo and org
|
||||
|
||||
Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in):
|
||||
Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in):
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one.
|
||||
The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say.
|
||||
|
||||
Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool.
|
||||
Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool.
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
@@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read:
|
||||
| Update / close a milestone | `milestone_write` | `"update"` |
|
||||
| Delete a milestone | `milestone_write` | `"delete"` |
|
||||
|
||||
Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution.
|
||||
Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution.
|
||||
|
||||
If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`.
|
||||
|
||||
@@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error.
|
||||
label_read method: "list_repo_labels" owner: <owner> repo: <repo> per_page: 50
|
||||
```
|
||||
|
||||
Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way
|
||||
to build a complete name → ID map — there is no lookup-by-name endpoint.
|
||||
Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete
|
||||
name → ID map, since there's no lookup-by-name endpoint.
|
||||
|
||||
Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable*
|
||||
per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as
|
||||
|
||||
@@ -19,7 +19,7 @@ metadata:
|
||||
- gitea-mcp-slim-go
|
||||
- context7-websites-gitea
|
||||
- context7-gitea-tea-cli
|
||||
version: "0.1.3"
|
||||
version: "0.1.4"
|
||||
|
||||
allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write
|
||||
---
|
||||
@@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in:
|
||||
Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.1"
|
||||
version: "0.1.2"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
@@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already:
|
||||
`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
@@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on.
|
||||
| Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. |
|
||||
| Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. |
|
||||
| Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. |
|
||||
| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. |
|
||||
| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. |
|
||||
|
||||
If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`.
|
||||
|
||||
@@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_
|
||||
|
||||
## Pagination
|
||||
|
||||
None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
|
||||
`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
|
||||
`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
|
||||
tools, so a caller assuming 30 will under-count pages needed for a fixed total.
|
||||
Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`.
|
||||
`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts
|
||||
pages needed.
|
||||
|
||||
@@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.3"
|
||||
version: "0.1.4"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
|
||||
@@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what
|
||||
2. Check the response's `is_pull` field:
|
||||
- `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead.
|
||||
- `false` or absent → it's an issue. Present the issue detail already retrieved.
|
||||
3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR."
|
||||
3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR."
|
||||
|
||||
If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write.
|
||||
|
||||
|
||||
@@ -23,19 +23,19 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing.
|
||||
- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`.
|
||||
- **404 can mean 403.** Gitea masks permission errors as not-found — check token scope before reporting a branch or commit missing.
|
||||
- **Nothing auto-paginates.** `list_branches`/`list_commits` return one page — iterate `page` until the count is below `per_page`.
|
||||
- **`delete_branch` has no force-push guard.** Treat deleting a protected branch as a hard refusal unless the user explicitly confirms it in the conversation. Check `protected` from `list_branches` first — a protected branch need not be named `main`.
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
Before any tool call, extract `owner` and `repo` from the git remote:
|
||||
Extract `owner` and `repo` from the git remote before any tool call — `get_me` and `list_my_repos` are blocked under this skill's token scope, so the remote is the only source:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -29,8 +29,7 @@ list_branches owner: <owner> repo: <repo>
|
||||
**Response:** one object per branch: `name`, `protected` (bool), `commit_sha` (present when the
|
||||
underlying commit data is available).
|
||||
|
||||
Paginate if you need the full list (see Gotchas in SKILL.md) — iterate `page` until the returned
|
||||
count is less than `per_page`.
|
||||
Paginate for the full list (see Gotchas) — iterate `page` until the count is less than `per_page`.
|
||||
|
||||
## `create_branch`
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ compatibility: Requires the Gitea MCP server configured with a token scoped to a
|
||||
is not actually required for any of this domain's five tools.
|
||||
|
||||
metadata:
|
||||
version: "1.0.0"
|
||||
version: "1.0.1"
|
||||
category: gitea
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
@@ -23,7 +23,7 @@ allowed-tools: mcp__gitea__get_file_contents mcp__gitea__get_dir_contents mcp__g
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **A 404 may mean an under-scoped token, not a missing path.** Every tool here gates on `write:repository`, and Gitea masks insufficient scope as 404. Check scopes first.
|
||||
- **404 may mean an under-scoped token, not a missing path.** These tools gate on `write:repository`; check scope before concluding the path is missing.
|
||||
- **Reads take `ref` (`tree_sha` on `get_repository_tree`), writes take `branch_name`.** One concept, three names — carry the wrong key and the branch is dropped.
|
||||
- **`content` is base64 both ways — except under `withLines: true`.** Encode before a write, decode after a read; but with `withLines: true` `content` is already plain JSON text and the reported `"encoding": "base64"` is a lie. Decoding it yields garbage.
|
||||
|
||||
|
||||
@@ -32,8 +32,8 @@ size. No recursion, no content, no `sha`.
|
||||
`get_repository_tree(owner, repo, tree_sha, recursive)`. Set `recursive: true` to walk
|
||||
subdirectories in one call.
|
||||
|
||||
The response sets `truncated: true` when one page does not hold every entry. Page through with
|
||||
`page`/`per_page` (defaults `1` and `30`) until a page returns fewer entries than `per_page`.
|
||||
The response sets `truncated: true` when one page doesn't hold every entry — page with
|
||||
`page`/`per_page` (defaults `1`/`30`) until a page returns fewer than `per_page`.
|
||||
|
||||
## Neither listing is a SHA source for a write
|
||||
|
||||
@@ -44,7 +44,6 @@ the canonical path for a write's SHA: one call returns the decoded content and t
|
||||
|
||||
## A 404 that is really a 403
|
||||
|
||||
These reads gate on `write:repository`, not on read access alone, and some Gitea endpoints answer
|
||||
an under-scoped token with 404 instead of 403 so they do not leak whether the resource exists. A
|
||||
404 on a path you are confident about is a scope problem until proven otherwise — check the token's
|
||||
configured scopes before concluding the file or directory does not exist.
|
||||
These reads gate on `write:repository`; an under-scoped token gets 404 instead of 403 so the
|
||||
endpoint doesn't leak whether the resource exists. On a path you're confident about, check token
|
||||
scope before concluding it doesn't exist.
|
||||
|
||||
@@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with write:issue and write:r
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.4"
|
||||
version: "0.1.5"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
@@ -29,17 +29,17 @@ allowed-tools: Bash mcp__gitea__list_issues mcp__gitea__issue_read mcp__gitea__i
|
||||
- **`list_issues` mixes in PRs unless you filter.** Issues and PRs share one number space; pass `type: "issues"` to exclude PRs (or `"pulls"`). `is_pull` is returned only by `issue_read method: "get"` — on a list item the only tell is `html_url`'s path segment (`/issues/` vs `/pulls/`).
|
||||
- **Label IDs and names are not interchangeable.** `issue_write` takes numeric IDs only; `list_issues` and `search_issues` filter by name; `issue_read "get"` returns names but `"get_labels"` returns full objects with IDs. Resolve via `gitea-labels-milestones` unless the caller named exact labels.
|
||||
- **A merge does not itself close the issue.** Gitea has no close-on-merge event, but a `Fixes #N` in the merged commits can, depending on merge style (`gitea-prs`). Re-read its state after a merge before closing it manually.
|
||||
- **A 404 may really be a 403.** Gitea hides permission errors as not-found — check the token's `write:issue` scope before concluding the issue does not exist.
|
||||
- **404 may mean 403.** Gitea hides permission errors as not-found — check `write:issue` scope before concluding the issue doesn't exist.
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
An orchestrating caller may pass `owner` and `repo` in already, and the `search` row is cross-repository and needs only a query — both skip this step. Otherwise, before any tool call:
|
||||
Skip if an orchestrating caller already passed `owner`/`repo` in, or the action is `search` (cross-repository, needs only a query). Otherwise, before any tool call:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is unset or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ list_issues owner: <owner> repo: <repo> state: "open" type: "issues"
|
||||
`updated_at`, and optionally `labels` (`[]string`), `milestone` (`{id, title}`), `ref`, `deadline`.
|
||||
Body and `closed_at` are omitted from list responses — call `issue_read method: "get"` for those.
|
||||
|
||||
Paginate with `page`/`per_page` until the returned count is less than `per_page`.
|
||||
Paginate: `page`/`per_page`, stop once the count is below `per_page`.
|
||||
|
||||
## `issue_read`
|
||||
|
||||
|
||||
@@ -16,30 +16,30 @@ metadata:
|
||||
- gitea-mcp-slim-go
|
||||
- context7-websites-gitea
|
||||
- context7-gitea-tea-cli
|
||||
version: "0.1.5"
|
||||
version: "0.1.6"
|
||||
|
||||
allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Applying a label takes a numeric ID, but issue/PR responses slim labels down to name strings.** An issue's existing labels yield no IDs — resolve name → ID with `label_read`.
|
||||
- **`pull_request_read` returns `milestone` as a bare title string** where `issue_read` returns `{id, title}` — recover the milestone's ID by listing milestones and matching the title.
|
||||
- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's own `exclusive` field.** `list_repo_labels` returns it on every repo label, so it is always *readable* per label; `label_write` documents it as "(org only)" because it is only *settable* through the org create methods. Where it is `true` Gitea enforces one-per-scope itself, and replacing rather than stacking on a label whose `exclusive` is `false` destroys a valid label.
|
||||
- **Applying a label needs a numeric ID; issue/PR responses give only name strings.** Resolve name → ID with `label_read` first.
|
||||
- **`pull_request_read` returns `milestone` as a bare title string, `issue_read` as `{id, title}`.** Recover the ID by listing milestones and matching the title.
|
||||
- **Never assume a `Kind/*`/`Priority/*`/`Status/*` scope is exclusive — read each label's `exclusive` field.** `list_repo_labels` always returns it; `label_write` can only set it via org create methods ("org only"). `true` means Gitea enforces one-per-scope; replacing instead of stacking on a `false` label destroys a valid one.
|
||||
|
||||
## Step 1 — Resolve owner, repo and org
|
||||
|
||||
Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in):
|
||||
Extract `owner` and `repo` from the git remote before any tool call (skip if an orchestrating caller already passed them in):
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it is the org name whenever the owner is an organisation, and the remote URL does not say whether it is one.
|
||||
The `*_org_label*` methods take `org`, not `owner`/`repo`. Pass that same `owner` as `org` — it's the org name whenever the owner is an organisation, which the remote URL doesn't say.
|
||||
|
||||
Read the failure text before interpreting it. `list_org_labels` needs the `read:organization` token scope, which this skill's declared scopes (`write:issue`, `write:repository`) do not carry, so it fails with `token does not have at least one of required scope(s), required=[read:organization]` *before* it ever determines org-vs-user. Report that: the org pool went unchecked, not empty. Only a not-found response is evidence the owner is a user account with no org pool.
|
||||
Read the failure text before interpreting it: `list_org_labels` needs `read:organization`, which this skill's declared scopes don't carry, so it fails with a scope error *before* it ever checks org-vs-user. Report the unchecked scope, not an empty pool — only a genuine not-found means the owner is a user account with no org pool.
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
@@ -58,6 +58,6 @@ Read the failure text before interpreting it. `list_org_labels` needs the `read:
|
||||
| Update / close a milestone | `milestone_write` | `"update"` |
|
||||
| Delete a milestone | `milestone_write` | `"delete"` |
|
||||
|
||||
Every list method paginates manually — `per_page` defaults to 30, so iterate `page: 1, 2, ...` until a page returns fewer results than `per_page`. A truncated list silently breaks name → ID resolution.
|
||||
Every list method paginates manually (`per_page` default 30) — iterate `page: 1, 2, ...` until a page returns fewer than `per_page`. A truncated list silently breaks name → ID resolution.
|
||||
|
||||
If the task is a label operation, read `references/labels.md`; if a milestone operation, read `references/milestones.md`. If the label to apply has to be derived from conversation context rather than named, read `references/label-inference.md`.
|
||||
|
||||
@@ -51,8 +51,8 @@ runtime error from Gitea rather than a client-side validation error.
|
||||
label_read method: "list_repo_labels" owner: <owner> repo: <repo> per_page: 50
|
||||
```
|
||||
|
||||
Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way
|
||||
to build a complete name → ID map — there is no lookup-by-name endpoint.
|
||||
Paginate (`page: 1, 2, ...`) until the count is below `per_page` — the only way to build a complete
|
||||
name → ID map, since there's no lookup-by-name endpoint.
|
||||
|
||||
Every returned repo label carries its own `exclusive` boolean, so exclusivity is always *readable*
|
||||
per repo label. That does not contradict `label_write`'s schema, which annotates `exclusive` as
|
||||
|
||||
@@ -19,7 +19,7 @@ metadata:
|
||||
- gitea-mcp-slim-go
|
||||
- context7-websites-gitea
|
||||
- context7-gitea-tea-cli
|
||||
version: "0.1.3"
|
||||
version: "0.1.4"
|
||||
|
||||
allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read mcp__gitea__pull_request_write mcp__gitea__pull_request_review_write
|
||||
---
|
||||
@@ -31,13 +31,13 @@ allowed-tools: Bash mcp__gitea__list_pull_requests mcp__gitea__pull_request_read
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
Extract them from the git remote before any tool call, skipping this when an orchestrating caller already passed them in:
|
||||
Extract from the git remote before any tool call, skipping this when an orchestrating caller already passed them in:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ compatibility: Requires Gitea MCP server configured with a token with write:repo
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.1"
|
||||
version: "0.1.2"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
@@ -33,13 +33,13 @@ allowed-tools: Bash mcp__gitea__list_releases mcp__gitea__get_release mcp__gitea
|
||||
|
||||
## Step 1 — Resolve owner and repo
|
||||
|
||||
`owner` and `repo` are required on every tool below. Extract them from the git remote, unless an orchestrating caller passed them in already:
|
||||
`owner` and `repo` are required on every tool below. Extract from the git remote, unless an orchestrating caller already passed them in:
|
||||
|
||||
```bash
|
||||
rtk git remote get-url origin
|
||||
```
|
||||
|
||||
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
No origin, or not a Gitea URL: stop and report "No Gitea remote found — set origin to your Gitea instance URL."
|
||||
|
||||
## Step 2 — Dispatch
|
||||
|
||||
@@ -68,6 +68,6 @@ These four are mutually exclusive — pick the one row the request lands on.
|
||||
| Create a release | Call `create_release` with `tag_name`, `target`, `title`, and `is_draft`/`is_pre_release` set explicitly — never left to default. This surface carries no update or edit tool, so a wrong flag is repairable only by delete-and-recreate (`references/conventions.md`). A separate `create_tag` is only needed to tag a commit without wrapping it in a release — whether `create_release` creates a missing tag is unconfirmed, so verify with `get_tag`. |
|
||||
| Delete a release | Resolve the numeric `id` per the first Gotcha, confirm intent, then call `delete_release`. The tag survives. |
|
||||
| Delete a tag along with its release | Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. |
|
||||
| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. |
|
||||
| List every page | Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries — nothing auto-paginates. |
|
||||
|
||||
If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, draft/prerelease semantics, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`.
|
||||
|
||||
@@ -70,7 +70,6 @@ id, tag_name, target, title, body, draft, prerelease, html_url, author, created_
|
||||
|
||||
## Pagination
|
||||
|
||||
None of the list tools auto-paginate. To collect a full result set, call with `page: 1`, then
|
||||
`page: 2`, etc., stopping when a page returns fewer items than `per_page`. `list_releases` and
|
||||
`list_tags` default `per_page` to 20 — lower than the 30-default used by most other gitea-mcp list
|
||||
tools, so a caller assuming 30 will under-count pages needed for a fixed total.
|
||||
Nothing auto-paginates. Loop `page: 1, 2, ...` until a page returns fewer items than `per_page`.
|
||||
`list_releases`/`list_tags` default `per_page` to 20, not the usual 30 — assuming 30 under-counts
|
||||
pages needed.
|
||||
|
||||
@@ -13,7 +13,7 @@ compatibility: Requires Gitea MCP server configured with a token; delegates all
|
||||
|
||||
metadata:
|
||||
category: integration
|
||||
version: "0.1.3"
|
||||
version: "0.1.4"
|
||||
source_keys:
|
||||
- gitea-mcp-repo
|
||||
- gitea-mcp-slim-go
|
||||
|
||||
@@ -14,7 +14,7 @@ The user has referenced a bare number without saying "issue" or "PR" (e.g. "what
|
||||
2. Check the response's `is_pull` field:
|
||||
- `true` → it's a PR. Invoke `gitea-prs` for full PR detail (status, diff, reviews as appropriate to the request) and present that instead.
|
||||
- `false` or absent → it's an issue. Present the issue detail already retrieved.
|
||||
3. If the resolution call 404s, don't conclude the number doesn't exist. Gitea hides permission errors as not-found (documented in `gitea-issues`' Gotchas), so report the 404 and suggest verifying the token carries `write:issue` rather than reporting "no such issue or PR."
|
||||
3. A 404 here isn't proof the number doesn't exist — Gitea hides permission errors as not-found (see `gitea-issues` Gotchas). Report the 404 and suggest checking the token's `write:issue` scope rather than reporting "no such issue or PR."
|
||||
|
||||
If the user stated an action on the number rather than asking about it, resolution is only step one: hand the action, with the resolved domain, to `gitea-issues` or `gitea-prs` to carry out. Presenting detail is not a substitute for performing the write.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user