gitea-infrastructure/.agents/skills/gitea/SKILL.md at 776b8a618e5eece2d7a23c6f9765d1f7f86b085d

mirror of https://github.com/terraphim/gitea-infrastructure.git synced 2026-07-16 01:00:33 +02:00

Files

Alex 776b8a618e 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-02-17 09:13:44 +00:00

8.8 KiB

Raw Blame History

name, description, license

name	description	license
gitea	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.	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:

REST API - Preferred for automation and scripting
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

Login to Gitea web UI
Go to Settings → Applications
Create new token with appropriate scopes

Using the Token

export GITEA_TOKEN="your-token-here"

Core Operations

Users

Create Admin User (requires admin CLI)

# Inside Gitea container
docker exec gitea gitea admin user create \
  --username <username> \
  --password <password> \
  --email <email> \
  --admin \
  --access-token

List Users (API)

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/admin/users"

Get User Info

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/users/{username}"

Organizations

Create Organization

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

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/orgs/{org}/repos"

Repositories

Create Repository

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

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

curl -s -X DELETE -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner}/{repo}"

List User Repositories

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/user/repos"

Issues

Create Issue

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

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues?state=all"

Get Issue

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner}/{repo}/issues/{index}"

Update 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 '{
    "title": "New title",
    "body": "Updated body",
    "state": "open"
  }'

Close/Reopen Issue

# 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

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

# 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

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner}/{repo}/pulls?state=all"

Get Pull Request

curl -s -H "Authorization: token $GITEA_TOKEN" \
  "$GITEA_URL/api/v1/repos/{owner}/{repo}/pulls/{index}"

Merge Pull Request

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

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

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

# 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

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

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

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:

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

Create issues for task tracking
Add labels for categorization
Assign to team members
Link to projects for board view
Update status via comments

Project Management

Create organization for team
Create project board
Add repositories to project
Add issues to project columns
Track progress via project API

Repository Automation

Initialize repositories with templates
Configure branch protection
Add deploy keys
Set up webhooks
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

8.8 KiB Raw Blame History