name: gitea-client
description: Gitea API client for job monitoring and PR management

# Gitea-Client Skill

A skill for interacting with Gitea API to monitor jobs, track PRs, and manage repository actions.

## Requirements

### Authentication

**Option 1: Environment Variable**
```bash
export GITEA_API_TOKEN="your_personal_access_token"
```

**Option 2: Token File** (Recommended for security)
```bash
export GITEA_API_TOKEN_FILE="/path/to/token_file"
```

Create a token in Gitea:
1. Go to your Gitea profile → Settings → Applications
2. Generate a new token with `read:repository`, `write:repository`, and `read:user` scopes
3. Either export it directly or save to a file and set GITEA_API_TOKEN_FILE

### API Documentation

- Swagger: https://gitea.arcodange.lab/swagger.v1.json
- Base URL: https://gitea.arcodange.lab

## Commands

### List Jobs

```bash
skill gitea-client list-jobs <owner> <repo> <workflow_id> [limit]
```

List workflow jobs for a repository.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `workflow_id`: Workflow ID
- `limit`: Maximum number of jobs to return (default: 10)

### Get Job Status

```bash
skill gitea-client job-status <owner> <repo> <job_id>
```

Get the current status of a specific job.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `job_id`: Job ID

### Get Job Logs

```bash
skill gitea-client job-logs <owner> <repo> <job_id> [output_file]
```

Fetch logs for a specific job.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `job_id`: Job ID
- `output_file`: Optional file to save logs (default: stdout)

**Examples:**
```bash
# Display logs in console
gitea-client job-logs arcodange DanceLessonsCoach 658

# Save logs to file
gitea-client job-logs arcodange DanceLessonsCoach 658 job_logs.txt
```

### Get Action Job Logs

```bash
skill gitea-client action-logs <owner> <repo> <action_job_id> [output_file]
```

Fetch logs for a specific action job (individual job within a workflow run).

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `action_job_id`: Action job ID (from workflow jobs list)
- `output_file`: Optional file to save logs (default: stdout)

**Examples:**
```bash
# Display action job logs
gitea-client action-logs arcodange DanceLessonsCoach 658

# Save to file for analysis
gitea-client action-logs arcodange DanceLessonsCoach 658 build_job_logs.txt
```

### List Workflow Jobs

```bash
skill gitea-client list-workflow-jobs <owner> <repo> <workflow_run_id>
```

List all jobs for a specific workflow run.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `workflow_run_id`: Workflow run ID

**Examples:**
```bash
# List all jobs for workflow run 350
gitea-client list-workflow-jobs arcodange DanceLessonsCoach 350
```

### Wait for Job Completion

```bash
skill gitea-client wait-job <owner> <repo> <job_id> [timeout]
```

Wait for a job to complete and return final status.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `job_id`: Job ID
- `timeout`: Maximum wait time in seconds (default: 300)

### Comment on PR

```bash
skill gitea-client comment-pr <owner> <repo> <pr_number> <comment>
```

Add a comment to a pull request.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `pr_number`: PR number
- `comment`: Comment text (use quotes for multi-word)

### Get PR Status

```bash
skill gitea-client pr-status <owner> <repo> <pr_number>
```

Get the current status of a pull request.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `pr_number`: PR number

## Workflows

### Monitor CI/CD Job

```bash
# List recent jobs
skill gitea-client list-jobs owner repo workflow_id 5

# Wait for specific job to complete
skill gitea-client wait-job owner repo job_id 600

# Get job logs if failed
skill gitea-client job-logs owner repo job_id
```

### Diagnose Failed Job

```bash
# Get job status
skill gitea-client job-status owner repo job_id

# List all jobs in the workflow run
skill gitea-client list-workflow-jobs owner repo workflow_run_id

# Fetch logs for specific action job
skill gitea-client action-logs owner repo action_job_id > action_logs.txt

# Fetch workflow run logs
skill gitea-client job-logs owner repo job_id > workflow_logs.txt

# Analyze logs and comment on PR
skill gitea-client comment-pr owner repo pr_number "Job failed: analysis results"
```

### Complete CI Debugging Workflow

```bash
# 1. Find recent failed jobs
skill gitea-client list-jobs owner repo workflow_id 5

# 2. Get status of failed job
skill gitea-client job-status owner repo failed_job_id

# 3. List all jobs in the workflow to find which ones failed
skill gitea-client list-workflow-jobs owner repo workflow_run_id

# 4. Fetch logs for each failed action job
for job_id in 658 659 660; do
    skill gitea-client action-logs owner repo $job_id ${job_id}_logs.txt
    echo "Saved logs for job $job_id to ${job_id}_logs.txt"
done

# 5. Search for errors in all logs
grep -i "error\|fail\|panic" *_logs.txt

# 6. Comment on PR with findings
skill gitea-client comment-pr owner repo pr_number "Found the issue: missing swagger docs generation"
```

## Examples

### Basic Job Monitoring

```bash
# List last 3 jobs for workflow 5
gitea-client list-jobs myorg myrepo 5 3

# Check status of job 12345
gitea-client job-status myorg myrepo 12345

# Wait up to 10 minutes for job completion
gitea-client wait-job myorg myrepo 12345 600
```

### PR Interaction

```bash
# Get PR status
gitea-client pr-status myorg myrepo 42

# Add comment to PR
gitea-client comment-pr myorg myrepo 42 "Build completed successfully!"
```

## Error Handling

The skill handles common API errors:
- 401 Unauthorized: Check your GITEA_API_TOKEN or GITEA_API_TOKEN_FILE
- 404 Not Found: Verify repository/owner and job/PR IDs
- 429 Too Many Requests: Wait and retry
- 500+ Server Errors: Retry or check Gitea status

## Best Practices

1. **Token Security**: Use GITEA_API_TOKEN_FILE for better security
2. **Rate Limiting**: Be mindful of API rate limits
3. **Error Handling**: Always check command exit codes
4. **Logging**: Redirect output to files for debugging
5. **Timeouts**: Use reasonable timeouts for wait operations

## Implementation Details

The skill uses:
- `curl` for HTTP requests
- `jq` for JSON processing
- Standard shell utilities
- Gitea REST API v1

All API calls include:
- Authorization header with token
- Proper error handling
- JSON response parsing
- Rate limit awareness

## Future Enhancements

- Webhook integration
- Advanced job filtering
- PR review management
- Repository administration
- Team management