# gitea plugin

Claude Code plugin for working with Gitea issues from any project. Ships a single skill (`gitea`) and a set of self-contained PEP 723 scripts that need no project-level Python setup — `uv run` builds an isolated env per script on first invocation.

## What it can do

| Task | Script |
|------|--------|
| Verify connectivity | `ping.py` |
| Fetch a ticket as markdown | `fetch_ticket.py` |
| Create an issue (inline or from a goal file) | `create_ticket.py` |
| Post a markdown file as a comment | `post_comment.py` |
| Start work on a ticket (branch + context) | `start_ticket.py` |
| List/search issues | `list_tickets.py` |
| Close issues | `close_ticket.py` |
| Scaffold standard labels in a new repo | `setup_labels.py` |

## Prerequisites

- [uv](https://docs.astral.sh/uv/) on PATH.
- A Gitea instance with API access and an API token.
- The project you're working in is a git clone of the Gitea repo (so the remote URL is parseable). If not, you can set `GITEA_URL`/`GITEA_OWNER`/`GITEA_REPO` explicitly.

## Gitea setup

1. Log into Gitea, go to **Settings → Applications → Manage Access Tokens**.
2. Generate a token with scopes:
   - `issue` — Read and Write
   - `repository` — Read and Write
3. Add it to a `.env` file in your project root (gitignored):

```env
GITEA_TOKEN=your_token_here
```

`GITEA_URL`, `GITEA_OWNER`, and `GITEA_REPO` are inferred from `git remote get-url origin`. Set them in `.env` only if you need to override the inferred values (mirrors, separate API host, etc.).

## Verify

```bash
uv run ${CLAUDE_PLUGIN_ROOT}/skills/gitea/scripts/ping.py
```

Should print the resolved URL/repo and `Connection: OK`.

## Bootstrap labels (optional)

```bash
uv run ${CLAUDE_PLUGIN_ROOT}/skills/gitea/scripts/setup_labels.py
```

Creates a default emoji-prefixed label set. Override per-project by placing `.gitea-labels.json` in the project root — its contents fully replace the default set.

## Architecture notes

- All scripts use **CWD-relative paths** for git, `.env`, and workpad lookups. The plugin directory is only consulted for shipped resources (like `labels.default.json`).
- Imports are **flat sibling imports** (`from client import …`) — scripts are run as files, not as a package.
- Each CLI entrypoint carries a PEP 723 `# /// script` header listing its own dependencies, so no shared environment, lockfile, or `pyproject.toml` is needed.

## See also

- The `gitea` skill's `SKILL.md` is the agent-facing reference. Read that to understand how Claude uses these scripts.
- A future sibling plugin will layer workflow glue (kanban, ticket-to-implementation flows) on top of this thin API surface.