gitea-issues

name	gitea-issues
description	Working with Gitea issues — reading tickets, posting progress updates, and managing dependencies. Load this skill at the start of any session where a Gitea issue number is provided.
license	MIT
compatibility	opencode

Prerequisites

This skill requires:

• agent-config.json at the project root — contains { "issue_tracker": { "provider": "gitea", "gitea": { "repo_url": "https://gitea.example.com/owner/repo" } } }. This file lives in the application repo being worked on, not in the OpenCode config repo. A GITEA_REPO_URL environment variable overrides the config value if set.
• GITEA_ACCESS_TOKEN — environment variable containing a Gitea personal access token with issue read/write scope. This is never stored in files.

See GITEA_SETUP.md for step-by-step setup instructions.

All Gitea tools gracefully return a configuration error message if the token or URL is missing — no crash, no silent failure.

Session start

When the user provides a ticket number at the start of a session:

1. Call gitea-get-issue with that number immediately.
2. Read the full issue: title, description, labels, state, assignees, and all comments. Comments are returned as part of gitea-get-issue output — no separate call is needed.
3. Check whether the issue has dependencies by calling gitea-manage-dependencies with action: "list". If blocking issues are open, surface them to the user before proceeding.
4. Treat the issue description as the source of truth for what needs to be done. If it conflicts with the user's verbal summary, surface the discrepancy and confirm before proceeding.
5. Post an opening comment using gitea-add-comment to signal that work has begun:

🚧 Picking up this ticket. Starting investigation.

Do not post the opening comment if the issue is already closed.

Reading comments

Comments are fetched automatically by gitea-get-issue and included in its output. Each comment shows the author, date, and body. Read them carefully — they often contain clarifications, prior investigation notes, review feedback, or scope changes that supersede the original description.

If a comment contradicts the issue body, the comment is more recent and should take precedence unless the user says otherwise.

During the work

Post progress comments at meaningful checkpoints — not after every file edit, but when a significant phase completes:

• After the implementation plan is confirmed
• After the first passing test (if TDD is in play)
• When blocked (with a description of the blocker)
• When handing off between agents (e.g. "backend complete, starting frontend")

Keep comments factual and brief. Examples:

✅ Implementation complete. Running reviewers now.

🔍 @code-reviewer passed. @security-reviewer passed. @observability-reviewer passed. Moving to QA.

🚫 Blocked: discovered that the `users` table is missing the `email_verified` column. Needs schema migration before this can proceed.

On completion

When all quality gates pass and the PR is opened, post a final comment:

✅ Complete. All quality gates passed.

PR: {pr_url}
Task log: agent-logs/YYYY-MM-DD-{slug}/log.md

Do not close the ticket. The user or the team manages ticket state — closing is not the agent's responsibility.

Updating issue body

Do not rewrite the issue body unless the user explicitly asks you to. The original description is the spec — preserve it.

If clarifications or scope changes emerge during the work, add them as comments rather than editing the body.

Dependencies

Gitea supports blocking dependencies between issues. Issue A depends on Issue B means B must be resolved before A can proceed.

Checking dependencies at session start — always list dependencies when picking up a ticket (see Session start above). If any blocking issue is still open, tell the user and ask whether to proceed anyway or pause.

Setting a dependency — if the user says this ticket is blocked by another, or if you discover during planning that a prerequisite ticket needs to exist first:

gitea-manage-dependencies
  action: "add"
  issue_number: <this ticket>
  dependency_issue_number: <the blocking ticket>

Removing a dependency — once a blocking issue is resolved:

gitea-manage-dependencies
  action: "remove"
  issue_number: <this ticket>
  dependency_issue_number: <the resolved ticket>

Important — internal IDs vs. display numbers: Gitea's dependency API requires the internal database id of an issue, not its display number. The gitea-manage-dependencies tool handles this automatically by resolving the display number to an internal ID before calling the API. Always pass display numbers (the #N you see in the UI) — never pass raw internal IDs.

Creating follow-up issues

If the work reveals a bug, tech debt, or deferred item that should be tracked, call gitea-create-issue to open a new ticket. Use the current issue number in the body for traceability:

Discovered during work on #N. [Description of the follow-up.]

If the new issue is a prerequisite for the current one, add a dependency immediately after creating it.

Label conventions

When creating issues, use labels that already exist in the repository. Do not invent new labels. Common conventions (confirm with the repo's label list before applying):

• bug — something is broken
• enhancement — new feature or improvement
• tech-debt — refactoring or cleanup
• blocked — cannot proceed without external action

Tool reference

Tool	When to use
gitea-get-issue	Session start; any time you need to re-read the ticket (includes comments)
gitea-list-issues	When the user asks to see open tickets or pick the next task
gitea-create-issue	Creating follow-up or child tickets
gitea-update-issue	Updating issue fields if the user explicitly requests it
gitea-manage-dependencies	Listing, adding, or removing blocking dependencies
gitea-create-pr	Opening a PR on completion — coordinated by the worktrees skill
gitea-add-comment	Progress updates, blockers, completion notes

Error handling

If any Gitea tool returns an error (network failure, bad token, missing repo):

1. Report the error to the user immediately — do not silently skip.
2. Do not retry automatically more than once.
3. Continue the engineering work regardless — ticket tracking must never block the actual task.