Issue tracker: Gitea

Issues and specs for this repo live as Gitea issues. Use the tea CLI, called tea-cli on some systems. Record the instance URL, repository owner/name, installed command version, and supported operations when adapting this template.

Access and conventions

Use the existing configured login and infer the repository from git remote -v. Check the installed binary's help before selecting commands: tea 1.0 changes the command groups, authentication, flags, and output formats. The examples here use tea-cli 0.9.2; options precede positional issue or PR numbers.

Authenticate: use the existing login; for a new login, run interactive tea-cli login add with the repository's instance URL.
Create an issue: tea-cli issues create --title "..." --description "..." --labels "needs-triage". Pass multiline descriptions as one quoted argument.
Read an issue: tea-cli issues --comments <number>.
List issues: tea-cli issues --state open --labels "..." --fields index,title,body,state,labels,assignees,url --output yaml. Paginate with --page and --limit until all matching issues have been read.
Comment: tea-cli comment <number> "...".
Close: post the explanation first, then tea-cli issues close <number>.
Pull requests: tea-cli pulls create --base <integration-branch> --title "..." --description "...", tea-cli pulls --comments <number>, and tea-cli pulls --state open --output yaml.
Milestones: tea-cli milestones --state all --fields id,title --output tsv. Verify migrated milestone IDs rather than copying source-tracker IDs.

This version has no JSON output, issue-edit command, or api command. Structured output flags apply to lists; detail views render for display. For unsupported operations, use the instance's /api/swagger explorer and /swagger.v1.json schema, or the Gitea UI. Authenticate API requests with an authorized token without displaying or committing it. API paths below are relative to the instance's /api/v1:

Read issue details and comments with GET /repos/<owner>/<repo>/issues/<number> and its /comments endpoint; paginate comments.
Resolve label IDs with GET /repos/<owner>/<repo>/labels. Add labels with POST /repos/<owner>/<repo>/issues/<number>/labels, body {"labels":[<label-id>]}; remove one with DELETE on /labels/<label-id>. Preserve unrelated labels.
Edit a body or assignment with PATCH /repos/<owner>/<repo>/issues/<number>, body {"body":"..."} or {"assignees":["<username>"]}. Read current assignees before updating the list.
Read a PR diff with GET /repos/<owner>/<repo>/pulls/<number>.diff.

Pull requests as a triage surface

PRs as a request surface: no. (Set to yes if this repo treats external pull requests as feature requests; /triage reads this flag.)

When enabled, read and list with tea-cli pulls; keep only external requests after checking collaborator or organization membership. Use tea-cli comment, the issue-label API, and tea-cli pulls close <number> for comment / label / close operations.

Resolve bare #<number> references by checking the resource kind with tea-cli issues --kind all --fields index,kind,title,url --output yaml or the issue API's pull_request field. Issue URLs use /issues/<number>; PR URLs use /pulls/<number>.

When a skill says "publish to the issue tracker"

Create a Gitea issue with tea-cli issues create.

When a skill says "fetch the relevant ticket"

Run tea-cli issues --comments <number> and read its labels and assignees.

Wayfinding operations

Map: an issue labelled wayfinder:map, holding the Notes / Decisions-so-far / Fog body. Create it with tea-cli issues create --title "..." --description "..." --labels "wayfinder:map".
Child ticket: an issue with Part of #<map> at the top of its description, labels wayfinder:<type> (research/prototype/grilling/task), and an ordered link in the map's body.
Blocking: POST /repos/<owner>/<repo>/issues/<child>/dependencies, body {"owner":"<owner>","repo":"<repo>","index":<blocker-number>}. GET lists blockers; DELETE with the same body removes one. Where native dependencies are unavailable, use Blocked by: #<n>, #<n> at the top of the description. Every blocker must be closed before the ticket is unblocked.
Frontier query: list all open children with bodies and assignees, drop assigned tickets and those with an open native or description-line blocker; first in map order wins.
Claim: assign the authenticated username through the issue API or Gitea UI — the session's first write.
Resolve: comment with tea-cli comment, close with tea-cli issues close, and update the map's Decisions-so-far through the issue API or Gitea UI.

4.7 KiB Raw Blame History