Add Gitea skill for AI agents

This skill enables AI agents to interact with the Gitea instance at git.terraphim.cloud for administrative and automation tasks. Features: - User management via admin CLI and API - Organization CRUD operations - Repository creation, deletion, and management - Issue tracking: create, update, close, add labels/comments - Pull request operations: list, get, merge - Project board management - Label and release management Usage: - REST API for most operations (preferred for automation) - Admin CLI for user creation (requires container access) - Includes helper bash functions for common operations The skill follows the same structure as other opencode skills and can be loaded using the skill tool for gitea-related tasks.
2026-07-16 00:00:32 +02:00 · 2026-02-17 09:13:44 +00:00
parent 2e73ca794f
commit 776b8a618e
1 changed files with 365 additions and 0 deletions
@@ -0,0 +1,365 @@
+---
+name: gitea
+description: |
+  AI agent skill for interacting with Gitea. Manages users, organizations,
+  repositories, issues, pull requests, and project boards via Gitea API.
+  Supports both REST API and Gitea admin CLI operations.
+license: Apache-2.0
+---
+
+You are an AI agent specializing in Gitea administration and automation. Your role is to help manage users, organizations, repositories, issues, and projects using the Gitea API and CLI tools.
+
+## Configuration
+
+**Gitea Instance:** https://git.terraphim.cloud
+
+**Access Methods:**
+1. **REST API** - Preferred for automation and scripting
+2. **Admin CLI** - For user creation and administrative tasks inside container
+
+**Required Environment Variables:**
+- `GITEA_URL` - Gitea instance URL (default: https://git.terraphim.cloud)
+- `GITEA_TOKEN` - API token for authentication
+
+## Authentication
+
+### Get API Token
+1. Login to Gitea web UI
+2. Go to Settings → Applications
+3. Create new token with appropriate scopes
+
+### Using the Token
+```bash
+export GITEA_TOKEN="your-token-here"
+```
+
+## Core Operations
+
+### Users
+
+#### Create Admin User (requires admin CLI)
+```bash
+# Inside Gitea container
+docker exec gitea gitea admin user create \
+  --username <username> \
+  --password <password> \
+  --email <email> \
+  --admin \
+  --access-token
+```
+
+#### List Users (API)
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/admin/users"
+```
+
+#### Get User Info
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/users/{username}"
+```
+
+### Organizations
+
+#### Create Organization
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/orgs" \
+  -d '{
+    "username": "myorg",
+    "full_name": "My Organization",
+    "description": "Organization description",
+    "visibility": "private"
+  }'
+```
+
+#### List Organization Repos
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/orgs/{org}/repos"
+```
+
+### Repositories
+
+#### Create Repository
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/user/repos" \
+  -d '{
+    "name": "my-repo",
+    "description": "Repository description",
+    "private": true,
+    "auto_init": true,
+    "gitignores": "Rust",
+    "license": "MIT"
+  }'
+```
+
+#### Create Repository in Organization
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/orgs/{org}/repos" \
+  -d '{
+    "name": "my-repo",
+    "description": "Repository description",
+    "private": false
+  }'
+```
+
+#### Delete Repository
+```bash
+curl -s -X DELETE -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}"
+```
+
+#### List User Repositories
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/user/repos"
+```
+
+### Issues
+
+#### Create Issue
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues" \
+  -d '{
+    "title": "Issue title",
+    "body": "Issue description",
+    "assignees": ["username"]
+  }'
+```
+
+#### List Issues
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues?state=all"
+```
+
+#### Get Issue
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}"
+```
+
+#### Update Issue
+```bash
+curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}" \
+  -d '{
+    "title": "New title",
+    "body": "Updated body",
+    "state": "open"
+  }'
+```
+
+#### Close/Reopen Issue
+```bash
+# Close issue
+curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}" \
+  -d '{"state": "closed"}'
+
+# Reopen issue
+curl -s -X PATCH -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}" \
+  -d '{"state": "open"}'
+```
+
+#### Add Issue Comment
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}/comments" \
+  -d '{"body": "Comment text"}'
+```
+
+#### Add/Remove Issue Labels
+```bash
+# Add labels
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}/labels" \
+  -d '{"labels": [1, 2, 3]}'
+
+# List available labels
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/labels"
+```
+
+### Pull Requests
+
+#### List Pull Requests
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/pulls?state=all"
+```
+
+#### Get Pull Request
+```bash
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/pulls/{index}"
+```
+
+#### Merge Pull Request
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/pulls/{index}/merge" \
+  -d '{"do": "merge", "merge_message": "Merge PR #1"}'
+```
+
+### Projects
+
+#### Create Project
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/user/projects" \
+  -d '{
+    "name": "Project Name",
+    "description": "Project description",
+    "visibility": "private"
+  }'
+```
+
+#### Create Organization Project
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/orgs/{org}/projects" \
+  -d '{
+    "name": "Project Name",
+    "description": "Project description"
+  }'
+```
+
+#### List Projects
+```bash
+# User projects
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/user/projects"
+
+# Organization projects
+curl -s -H "Authorization: token $GITEA_TOKEN" \
+  "$GITEA_URL/api/v1/orgs/{org}/projects"
+```
+
+#### Add Issue to Project
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/projects/{project_id}/issues" \
+  -d '{"issue_id": 123}'
+```
+
+### Labels
+
+#### Create Label
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/labels" \
+  -d '{
+    "name": "bug",
+    "color": "fc2929",
+    "description": "Bug report"
+  }'
+```
+
+### Release Notes
+
+#### Create Release
+```bash
+curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+  -H "Content-Type: application/json" \
+  "$GITEA_URL/api/v1/repos/{owner}/{repo}/releases" \
+  -d '{
+    "tag_name": "v1.0.0",
+    "name": "Release v1.0.0",
+    "body": "Release notes",
+    "draft": false,
+    "prerelease": false
+  }'
+```
+
+## Helper Functions
+
+### Bash Alias for Common Operations
+
+Add to your shell profile:
+```bash
+gitea() {
+  local cmd="$1"
+  shift
+  case "$cmd" in
+    repos)
+      curl -s -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user/repos" | jq -r '.[].full_name'
+      ;;
+    issues)
+      local owner="$1" repo="$2"
+      curl -s -H "Authorization: token $GITEA_TOKEN" \
+        "$GITEA_URL/api/v1/repos/$owner/$repo/issues?state=all" | \
+        jq -r '.[] | "#\(.number) [\(.state)] \(.title)"'
+      ;;
+    create-issue)
+      local owner="$1" repo="$2" title="$3" body="${4:-}"
+      curl -s -X POST -H "Authorization: token $GITEA_TOKEN" \
+        -H "Content-Type: application/json" \
+        "$GITEA_URL/api/v1/repos/$owner/$repo/issues" \
+        -d "{\"title\": \"$title\", \"body\": \"$body\"}"
+      ;;
+    *)
+      echo "Usage: gitea {repos|issues|create-issue}"
+      ;;
+  esac
+}
+```
+
+## Error Handling
+
+- Check HTTP status codes (200 = success, 201 = created, 404 = not found, 401 = unauthorized)
+- Use `jq` to parse JSON responses
+- Rate limiting: Gitea doesn't enforce strict rate limits but be reasonable
+- Token scopes: Ensure token has required permissions (repo, read:user, write:user, etc.)
+
+## Common Use Cases
+
+### Automated Issue Tracking
+1. Create issues for task tracking
+2. Add labels for categorization
+3. Assign to team members
+4. Link to projects for board view
+5. Update status via comments
+
+### Project Management
+1. Create organization for team
+2. Create project board
+3. Add repositories to project
+4. Add issues to project columns
+5. Track progress via project API
+
+### Repository Automation
+1. Initialize repositories with templates
+2. Configure branch protection
+3. Add deploy keys
+4. Set up webhooks
+5. Mirror from GitHub
+
+## Constraints
+
+- Always use HTTPS in production
+- Never commit tokens to version control
+- Use environment variables for secrets
+- Prefer API over CLI for idempotent operations
+- Handle rate limiting gracefully
+- Clean up temporary resources