feat: implement admin API (users, orgs, cron, hooks) #13

New Issue

2026-06-02T06:57:02Z

a-limasov commented

2026-06-02 06:57:02 +00:00

Context

Admin endpoints allow Gitea instance administrators to manage users, organisations,
and server tasks without logging into the web UI. Required for automated provisioning,
user onboarding pipelines, and scheduled maintenance.

Endpoints to implement

Method	Path	Tool name	Description
GET	`/admin/users`	`admin_list_users`	List all users on the instance
POST	`/admin/users`	`admin_create_user`	Create a user
PATCH	`/admin/users/{username}`	`admin_edit_user`	Edit user account
DELETE	`/admin/users/{username}`	`admin_delete_user`	Delete a user
POST	`/admin/users/{username}/repos`	`admin_create_user_repo`	Create repo for user
POST	`/admin/users/{username}/rename`	`admin_rename_user`	Rename a user
POST	`/admin/users/{username}/orgs`	`admin_create_org`	Create org for user
GET	`/admin/orgs`	`admin_list_orgs`	List all organizations
GET	`/admin/hooks`	`admin_list_hooks`	List global webhooks
POST	`/admin/hooks`	`admin_create_hook`	Create global webhook
PATCH	`/admin/hooks/{id}`	`admin_edit_hook`	Edit global webhook
DELETE	`/admin/hooks/{id}`	`admin_delete_hook`	Delete global webhook
GET	`/admin/cron`	`admin_list_cron`	List cron tasks
POST	`/admin/cron/{task}`	`admin_run_cron`	Trigger a cron task
GET	`/admin/emails`	`admin_list_emails`	List all user emails
GET	`/admin/emails/search`	`admin_search_emails`	Search emails

Acceptance Criteria

All admin_* tools document in their docstring that they require admin privileges
admin_create_user accepts: username, email, password, must_change_password, send_notify
admin_delete_user returns {"success": true} on 204; docstring warns about irreversibility
admin_list_users supports limit and page pagination
admin_run_cron(task) returns {"success": true} on 204

Technical Notes

POST /admin/users body: {"username": "alice", "email": "alice@example.com", "password": "...", "must_change_password": true}
PATCH /admin/users/{username} body: subset of user fields — all optional
Admin endpoints return 403 if the authenticated user is not a site admin
Global hooks (/admin/hooks) fire for all repositories on the instance

## Context Admin endpoints allow Gitea instance administrators to manage users, organisations, and server tasks without logging into the web UI. Required for automated provisioning, user onboarding pipelines, and scheduled maintenance. ## Endpoints to implement | Method | Path | Tool name | Description | |--------|------|-----------|-------------| | GET | `/admin/users` | `admin_list_users` | List all users on the instance | | POST | `/admin/users` | `admin_create_user` | Create a user | | PATCH | `/admin/users/{username}` | `admin_edit_user` | Edit user account | | DELETE | `/admin/users/{username}` | `admin_delete_user` | Delete a user | | POST | `/admin/users/{username}/repos` | `admin_create_user_repo` | Create repo for user | | POST | `/admin/users/{username}/rename` | `admin_rename_user` | Rename a user | | POST | `/admin/users/{username}/orgs` | `admin_create_org` | Create org for user | | GET | `/admin/orgs` | `admin_list_orgs` | List all organizations | | GET | `/admin/hooks` | `admin_list_hooks` | List global webhooks | | POST | `/admin/hooks` | `admin_create_hook` | Create global webhook | | PATCH | `/admin/hooks/{id}` | `admin_edit_hook` | Edit global webhook | | DELETE | `/admin/hooks/{id}` | `admin_delete_hook` | Delete global webhook | | GET | `/admin/cron` | `admin_list_cron` | List cron tasks | | POST | `/admin/cron/{task}` | `admin_run_cron` | Trigger a cron task | | GET | `/admin/emails` | `admin_list_emails` | List all user emails | | GET | `/admin/emails/search` | `admin_search_emails` | Search emails | ## Acceptance Criteria - [ ] All `admin_*` tools document in their docstring that they require admin privileges - [ ] `admin_create_user` accepts: `username`, `email`, `password`, `must_change_password`, `send_notify` - [ ] `admin_delete_user` returns `{"success": true}` on 204; docstring warns about irreversibility - [ ] `admin_list_users` supports `limit` and `page` pagination - [ ] `admin_run_cron(task)` returns `{"success": true}` on 204 ## Technical Notes - `POST /admin/users` body: `{"username": "alice", "email": "alice@example.com", "password": "...", "must_change_password": true}` - `PATCH /admin/users/{username}` body: subset of user fields — all optional - Admin endpoints return 403 if the authenticated user is not a site admin - Global hooks (`/admin/hooks`) fire for all repositories on the instance

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: a-limasov/gitea-platform-mcp#13