From 776b8a618e5eece2d7a23c6f9765d1f7f86b085d Mon Sep 17 00:00:00 2001 From: Alex Date: Tue, 17 Feb 2026 09:13:44 +0000 Subject: [PATCH] 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. --- .agents/skills/gitea/SKILL.md | 365 ++++++++++++++++++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100644 .agents/skills/gitea/SKILL.md diff --git a/.agents/skills/gitea/SKILL.md b/.agents/skills/gitea/SKILL.md new file mode 100644 index 0000000..a37a5be --- /dev/null +++ b/.agents/skills/gitea/SKILL.md @@ -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 \ + --password \ + --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