gitea-infrastructure/.agents/skills/gitea/SKILL.md

---
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