dance-lessons-coach/.vibe/skills/gitea-client/SKILL.md

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

**Web UI Link:**
The response includes a `html_url` field that provides a direct link to view the job in Gitea's web interface.

**Example:**
```bash
# Get job status and extract web UI link
gitea-client job-status arcodange DanceLessonsCoach 351 | jq '.html_url'
# Output: "https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/3"
```

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

**Web UI Links:**
Each job in the response includes a `html_url` field for direct access to that specific job's web interface.

**Example:**
```bash
# List all jobs and extract their web UI links
gitea-client list-workflow-jobs arcodange DanceLessonsCoach 351 | jq '.jobs[] | "Job \(.id): \(.name) - \(.html_url)"'
```

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

## Real-World Use Case: PR Commenting Workflow

The Gitea client skill excels at automated PR commenting during CI/CD workflows.

### Example: Automated PR Feedback

```bash
# Scenario: CI job fails, diagnose and comment on PR

# 1. Find the PR associated with this branch
PR_NUMBER=$(gitea-client list-prs arcodange DanceLessonsCoach \
  | jq -r '.[] | select(.head.ref == "ci/trunk-based-development") | .number')

# 2. Monitor CI job status
JOB_ID=352
JOB_STATUS=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.status')

# 3. If job fails, diagnose and comment
if [ "$JOB_STATUS" = "completed" ]; then
    CONCLUSION=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.conclusion')
    
    if [ "$CONCLUSION" = "failure" ]; then
        # Get detailed logs
        gitea-client job-logs arcodange DanceLessonsCoach $JOB_ID job_logs.txt
        
        # Find error patterns
        ERRORS=$(grep -i "error\|fail\|panic" job_logs.txt | head -5)
        
        # Comment on PR with findings
        gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER \
            "⚠️ CI Job Failed: $JOB_ID\n\n🔍 Diagnosis:\n$ERRORS\n\n📊 Job Details: $(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.html_url')"
    fi
fi

# 4. Success case - comment on successful build
if [ "$CONCLUSION" = "success" ]; then
    gitea-client comment-pr arcodange DanceLessonsCoach $PR_NUMBER \
        "✅ CI Job Passed: $JOB_ID\n\n🎉 All checks successful!\n\n📊 Job Details: $(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.html_url')"
fi
```

### Real Example from This Project

```bash
# Actual commands used to comment on PR #1:

# Add summary comment
gitea-client comment-pr arcodange DanceLessonsCoach 1 \
    "🎉 Comprehensive PR Summary\n\nThis PR includes CI improvements and new Gitea client skill."

# Add detailed breakdown
gitea-client comment-pr arcodange DanceLessonsCoach 1 \
    "📋 This PR includes 5 key improvements:\n\n1. 🤖 Gitea Client Skill\n2. 🐛 Swagger Generation Fix\n3. ⚡ Performance Optimization\n4. 🔧 Workflow Validation\n5. 📖 Documentation Updates"
```

### Benefits of Automated PR Commenting

1. **Immediate Feedback**: Developers get instant CI results
2. **Rich Context**: Comments include direct links to jobs and logs
3. **Consistency**: Standardized feedback format
4. **Traceability**: All CI events documented in PR timeline
5. **Collaboration**: Bridges gap between automation and human review

### Advanced Patterns

```bash
# Comment with job comparison
PREV_JOB=350
CURRENT_JOB=352

gitea-client comment-pr arcodange DanceLessonsCoach 1 \
    "📊 CI Performance Improvement:\n\n- Job $PREV_JOB: ❌ Failed (missing swag)\n- Job $CURRENT_JOB: ⏳ In Progress (with fixes)\n\n🎯 Expected: Faster execution, better reliability"

# Comment with log snippets
gitea-client job-logs arcodange DanceLessonsCoach $CURRENT_JOB > current_logs.txt
ERROR_LINE=$(grep -n "pattern docs/swagger.json" current_logs.txt | head -1)

gitea-client comment-pr arcodange DanceLessonsCoach 1 \
    "🔍 Error Analysis:\n\nPrevious error (Job $PREV_JOB):\n> pkg/server/server.go:30:12: pattern docs/swagger.json: no matching files found\n\nCurrent fix:\n> Added: go install github.com/swaggo/swag/cmd/swag@latest\n> Result: Files now generate properly ✅"
```

## Integration with CI Workflows

Add PR commenting to your GitHub Actions workflow:

```yaml
- name: Comment PR on failure
  if: failure()
  run: |
    PR_NUMBER=$(gitea-client list-prs owner repo | jq -r ".[] | select(.head.ref == '\${{ github.ref_name }}') | .number")
    if [ -n "$PR_NUMBER" ]; then
      gitea-client comment-pr owner repo $PR_NUMBER \
        "❌ Build failed: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
    fi
```

## Web UI Integration

All API responses include `html_url` fields that provide direct links to Gitea's web interface. Use these to:

```bash
# Get web UI link for a job
job_url=$(gitea-client job-status owner repo job_id | jq -r '.html_url')
echo "View in browser: $job_url"

# Open job directly in browser (macOS)
open $(gitea-client job-status owner repo job_id | jq -r '.html_url')

# Linux/WSL
xdg-open $(gitea-client job-status owner repo job_id | jq -r '.html_url')
```

**Common URL Patterns:**
- Job: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/{run_id}`
- Workflow: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions`
- PR: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/pulls/{pr_number}`

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