oval/goose-gitea-guide
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Page: Home
Pages
Configuration Home Installation SSH Setup Troubleshooting Usage
Clone
3
Home
Ole Valente edited this page 2026-07-07 18:08:07 +02:00
Table of Contents

Goose + Gitea — Complete Integration Guide

This guide documents how to integrate a self-hosted Gitea instance with Goose (the AI agent harness) using the official gitea-mcp MCP server — v1.3.0 with 53 tools.

Architecture

┌──────────┐     stdio MCP      ┌──────────────┐      REST API      ┌──────────┐
│  Goose   │ ◄────────────────► │  gitea-mcp   │ ◄────────────────► │  Gitea   │
│ (agent)  │    (stdin/stdout)  │  (Go binary) │   (HTTPS, token)  │  Server  │
└──────────┘                    └──────────────┘                    └──────────┘
  • Goose spawns gitea-mcp as a child process on demand — no background servers
  • gitea-mcp translates MCP tool calls into Gitea REST API calls
  • SSH (port 222) is configured separately for git clone/push/pull

What You Get — 53 Tools

Repositories & Files

create_repo, fork_repo, list_my_repos, list_org_repos, search_repos, create_or_update_file, delete_file, get_file_contents, get_dir_contents, get_repository_tree

Branches & Tags

create_branch, delete_branch, list_branches, create_tag, delete_tag, list_tags, get_tag

Commits & Releases

list_commits, get_commit, create_release, delete_release, get_release, get_latest_release, list_releases

Issues & Pull Requests

issue_read, issue_write, list_issues, search_issues, pull_request_read, pull_request_write, pull_request_review_write, list_pull_requests

Labels & Milestones

label_read, label_write, milestone_read, milestone_write

Actions (CI/CD)

actions_config_read, actions_config_write, actions_run_read, actions_run_write

Wiki & Packages

wiki_read, wiki_write, package_read, package_write

Other

get_me, get_user_orgs, search_org_teams, search_users, notification_read, notification_write, timetracking_read, timetracking_write, get_gitea_mcp_server_version

Setup Steps

  1. Installation — Download and install the gitea-mcp binary
  2. Configuration — The exact config.yaml entry
  3. SSH Setup — For git push/pull/clone over port 222
  4. Start a brand new chat in Goose (existing sessions cache extensions)
  5. Usage — Examples of what to ask Goose
  6. Troubleshooting — Common issues and fixes

Reference Setup

Component Value
Gitea instance https://gt.covalente.dk
SSH port 222/tcp
gitea-mcp version 1.3.0
Binary path /usr/local/bin/gitea-mcp
Goose version 1.41.0