g4borg
68c112d2c8
Ports dirigent's gitea scripts into a self-contained reliquary plugin. Scripts run via uv with PEP 723 inline deps — no project venv needed. Gitea connection inferred from `git remote get-url origin` with env-var overrides; only GITEA_TOKEN is mandatory. Workpad path and tickets directory are parameterized so the plugin works in any project. Label set externalized to labels.default.json with project-level override via .gitea-labels.json. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
64 lines
2.6 KiB
Markdown
64 lines
2.6 KiB
Markdown
# 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.
|