opencode-plugin-gitea

A full Gitea integration plugin for opencode — auth, git operations, repositories, issues, pull requests, releases, labels, milestones, webhooks, notifications, organizations, teams, search, Actions, packages, wiki, and a sidebar panel.

Works on Linux (all distros), macOS, and Windows.

Features

• ~87 chat-invokable tools — all namespaced gitea_*
• 8 slash commands — /gitea-setup, /gitea-status, /gitea-pr, /gitea-clone, /gitea-issue, /gitea-release, /gitea-merge, /gitea-notifications, /gitea-search
• Sidebar panel — leader + g toggles a right-hand panel showing repo, branch, ahead/behind, dirty status, open PRs, my issues, unread notifications, and CI runs
• Auth — API token (paste from Gitea) or OAuth2
• Git operations — clone, pull, push, fetch, status, log, diff, branch, checkout, stash, commit, ahead/behind
• Workspace adapter — open a remote Gitea repo as an opencode workspace
• Gitea Models provider — auto-detect Gitea Models at /api/v1/models and register them as an opencode LLM provider
• Multi-server — configure multiple Gitea/Forgejo instances side by side
• Shell env injection — GITEA_TOKEN, GITEA_URL, GITEA_SERVER set per-shell so git CLI auth works automatically

Install

npm install -g opencode-plugin-gitea
opencode-plugin-gitea install-assets   # copies slash commands + skill to config dir

Add to ~/.config/opencode/opencode.json (or %USERPROFILE%\.config\opencode\opencode.json on Windows):

{
  "plugin": [["opencode-plugin-gitea", {
    "servers": {
      "default": { "url": "https://gitea.example.com" }
    }
  }]]
}

Then in any opencode session, run:

/gitea-setup

Follow the prompts to paste your API token (Settings → Applications → Generate New Token, with scopes: repo, issue, notification, user, organization, package).

Quick start

| Action | Command | |---|---| | Authenticate | /gitea-setup | | Toggle sidebar | leader + g | | Quick overview | /gitea-status | | Create a PR | /gitea-pr main | | Clone a repo | /gitea-clone myorg/myrepo | | Open an issue | /gitea-issue | | Release | /gitea-release v1.0.0 | | Merge PR | /gitea-merge 42 | | Search | /gitea-search query | | Notifications | /gitea-notifications |

Available tools (invoke in chat):

| Namespace | Tools | |---|---| | Repo | gitea_repo_search, gitea_repo_list, gitea_repo_view, gitea_repo_create, gitea_repo_fork, gitea_repo_clone, gitea_repo_delete, gitea_repo_open | | Files | gitea_file_get, gitea_file_create, gitea_file_update, gitea_file_delete, gitea_file_history | | Git | gitea_git_pull, gitea_git_push, gitea_git_fetch, gitea_git_status, gitea_git_log, gitea_git_diff, gitea_git_branch_list, gitea_git_branch_create, gitea_git_branch_delete, gitea_git_checkout, gitea_git_stash_push, gitea_git_stash_pop, gitea_git_commit, gitea_git_ahead_behind | | Issues | gitea_issue_list, gitea_issue_view, gitea_issue_create, gitea_issue_edit, gitea_issue_comment, gitea_issue_comment_list | | PRs | gitea_pr_list, gitea_pr_view, gitea_pr_create, gitea_pr_edit, gitea_pr_merge, gitea_pr_review_create, gitea_pr_commits | | Releases | gitea_release_list, gitea_release_create, gitea_release_edit, gitea_release_delete, gitea_tag_list, gitea_tag_create | | Labels / milestones | gitea_label_list/create/edit/delete, gitea_milestone_list/create/edit/delete | | Notifications | gitea_notification_list, gitea_notification_read, gitea_notification_read_all | | Webhooks | gitea_webhook_list, gitea_webhook_create, gitea_webhook_edit, gitea_webhook_delete | | Users / orgs / search | gitea_whoami, gitea_user_view, gitea_user_search, gitea_search_code, gitea_org_list/view/create, gitea_team_list/create/add_member/remove_member | | Actions / packages / wiki | gitea_actions_runs/view/rerun/cancel, gitea_package_list/delete, gitea_wiki_list/get/create |

Cross-platform

| Concern | Linux | macOS | Windows | |---|---|---|---| | Config dir | ~/.config/opencode/ | ~/.config/opencode/ | %USERPROFILE%\.config\opencode\ | | Secret file | ~/.config/opencode/gitea.cred (0600) | same | same (user-profile ACL) | | Browser open | xdg-open | open | cmd /c start | | Git spawn | spawn("git", …, { shell: false }) — identical on every platform | | |

The plugin is pure JavaScript with no native modules — runs on any platform with Node.js 20+.

Configuration

Plugin options (in opencode.json)

["opencode-plugin-gitea", {
  "servers": {
    "default": { "url": "https://gitea.example.com", "defaultOwner": "myorg" },
    "work": { "url": "https://gitea.work.com" }
  },
  "defaultServer": "default",
  "cloneDir": "~/code",
  "scopes": ["repo", "issue", "notification", "user", "organization"],
  "sidebar": {
    "visible": false,
    "pollIntervalSec": 30,
    "maxRows": 5,
    "sections": { "prs": true, "issues": true, "notifications": true, "ci": true, "activity": false }
  },
  "modelProvider": { "enabled": true }
}]

Environment variables

| Variable | Purpose | |---|---| | GITEA_URL | Override default server URL | | GITEA_TOKEN | Override default server token | | GITEA_SERVER | Select server by name | | GITEA_OWNER | Explicit owner (avoid remote resolution) | | GITEA_REPO | Explicit repo (avoid remote resolution) |

Development

git clone <url>
cd opencode-plugin-gitea
npm install
npm run build     # tsc → dist/
npm test          # vitest
npm run lint      # tsc --noEmit

# local test install
opencode-plugin-gitea install-assets

To publish:

npm run build
npm publish

License

MIT