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

---
name: gitea-client
description: Gitea API client for job monitoring and PR management
license: MIT
metadata:
  author: dance-lessons-coach Team
  version: "1.0.0"
---

# 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 JSON**: https://gitea.arcodange.lab/swagger.v1.json
- **Base URL**: https://gitea.arcodange.lab
- **Official Docs**: https://gitea.com/api/swagger

**Tip:** See the [REFERENCE.md](#reference) for detailed guidance on discovering and exploring Gitea API endpoints using the Swagger documentation.

## Commands

### List Workflows

```bash
skill gitea-client list-workflows <owner> <repo>
```

List available workflows for a repository.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name

### 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 dance-lessons-coach 351 | jq '.html_url'
# Output: "https://gitea.arcodange.lab/arcodange/dance-lessons-coach/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 dance-lessons-coach 658

# Save logs to file
gitea-client job-logs arcodange dance-lessons-coach 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 dance-lessons-coach 658

# Save to file for analysis
gitea-client action-logs arcodange dance-lessons-coach 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 dance-lessons-coach 351 | jq '.jobs[] | "Job \(.id): \(.name) - \(.html_url)"'
```

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

### Monitor Workflow Run

```bash
skill gitea-client monitor-workflow <owner> <repo> <workflow_run_id> [interval_seconds]
```

Monitor a workflow run until completion with automatic updates.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `workflow_run_id`: Workflow run ID
- `interval_seconds`: Update interval in seconds (default: 30)

**Example:**
```bash
# Monitor workflow run 415 with 30-second updates
gitea-client monitor-workflow arcodange dance-lessons-coach 415 30

# Monitor with faster updates (10 seconds)
gitea-client monitor-workflow arcodange dance-lessons-coach 415 10
```

### Diagnose Failed Job

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

Diagnose a failed job with automatic error analysis.

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

**Features:**
- Shows job details (status, conclusion, timestamps)
- Displays last 50 lines of logs
- Automatically extracts and highlights error messages
- Shows workflow run context

**Example:**
```bash
# Diagnose failed job 759
gitea-client diagnose-job arcodange dance-lessons-coach 759
```

### Get Recent Workflows Summary

```bash
skill gitea-client recent-workflows <owner> <repo> [limit] [status_filter]
```

Get a summary of recent workflow runs.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `limit`: Maximum number of workflows to show (default: 10)
- `status_filter`: Filter by status (optional: completed, in_progress, queued, waiting)

**Example:**
```bash
# Show last 5 workflow runs
gitea-client recent-workflows arcodange dance-lessons-coach 5

# Show only completed workflows
gitea-client recent-workflows arcodange dance-lessons-coach 10 completed

# Show in-progress workflows
gitea-client recent-workflows arcodange dance-lessons-coach 5 in_progress
```

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

### List Issues

```bash
skill gitea-client list-issues <owner> <repo> [state]
```

List issues for a repository.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `state`: Issue state (open, closed, all) - default: open

**Examples:**
```bash
# List open issues
gitea-client list-issues arcodange dance-lessons-coach

# List closed issues
gitea-client list-issues arcodange dance-lessons-coach closed

# List all issues
gitea-client list-issues arcodange dance-lessons-coach all
```

### Create Issue

```bash
skill gitea-client create-issue <owner> <repo> <title> <description>
```

Create a new issue in the repository.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `title`: Issue title
- `description`: Issue description (use quotes)

**Examples:**
```bash
# Create a simple issue
gitea-client create-issue arcodange dance-lessons-coach "Bug in CI workflow" "The CI workflow fails on job 350"

# Create detailed issue with multi-line description
gitea-client create-issue arcodange dance-lessons-coach "Optimize main branch workflow" "Current workflow has separate version bump and Docker build steps. Need to optimize by:

1. Share artifacts between CI jobs for faster execution
2. Combine version management and Docker build in single workflow
3. Use proper job dependencies and artifact caching
4. Reduce total CI time by avoiding redundant builds"
```

### Show Issue Details

```bash
skill gitea-client show-issue <owner> <repo> <issue_number>
```

Get detailed information about a specific issue.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `issue_number`: Issue number

**Examples:**
```bash
# Show issue details
gitea-client show-issue arcodange dance-lessons-coach 42

# Get issue and extract title
gitea-client show-issue arcodange dance-lessons-coach 42 | jq '.title'
```

### Comment on Issue

```bash
skill gitea-client comment-issue <owner> <repo> <issue_number> <comment>
```

Add a comment to an existing issue.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `issue_number`: Issue number
- `comment`: Comment text (use quotes)

**Examples:**
```bash
# Add simple comment
gitea-client comment-issue arcodange dance-lessons-coach 42 "Working on this now"

# Add detailed update
gitea-client comment-issue arcodange dance-lessons-coach 42 "Created optimized workflow in .gitea/workflows/main-branch-optimized.yaml. Ready for testing."
```

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

### Issue Management Workflow

```bash
# 1. List open issues
gitea-client list-issues arcodange dance-lessons-coach

# 2. Create new issue for workflow optimization
gitea-client create-issue arcodange dance-lessons-coach "Optimize main branch workflow" "Current workflow has separate version bump and Docker build steps. Need to optimize by:

1. Share artifacts between CI jobs for faster execution
2. Combine version management and Docker build in single workflow
3. Use proper job dependencies and artifact caching
4. Reduce total CI time by avoiding redundant builds"

# 3. Show issue details
gitea-client show-issue arcodange dance-lessons-coach 42

# 4. Add progress comment
gitea-client comment-issue arcodange dance-lessons-coach 42 "Created optimized workflow in .gitea/workflows/main-branch-optimized.yaml. Ready for testing."

# 5. Close issue when resolved
gitea-client comment-issue arcodange dance-lessons-coach 42 "✅ RESOLVED: Optimized workflow implemented and tested successfully."
```

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

## Enhanced Workflow Monitoring with New Commands

### Complete CI Debugging Workflow with New Commands

```bash
# 1. Get summary of recent workflows to identify issues
gitea-client recent-workflows arcodange dance-lessons-coach 10

# 2. Monitor a specific workflow run until completion
gitea-client monitor-workflow arcodange dance-lessons-coach 415 30

# 3. If workflow fails, automatically diagnose all failed jobs
WORKFLOW_ID=415
WORKFLOW_STATUS=$(gitea-client job-status arcodange dance-lessons-coach $WORKFLOW_ID | jq -r '.status')
WORKFLOW_CONCLUSION=$(gitea-client job-status arcodange dance-lessons-coach $WORKFLOW_ID | jq -r '.conclusion')

if [ "$WORKFLOW_CONCLUSION" = "failure" ]; then
    echo "Workflow failed! Diagnosing all jobs..."
    
    # Get all jobs in the workflow
    JOBS=$(gitea-client list-workflow-jobs arcodange dance-lessons-coach $WORKFLOW_ID | jq -r '.jobs[] | select(.conclusion == "failure") | .id')
    
    # Diagnose each failed job
    for job_id in $JOBS; do
        echo "Diagnosing job $job_id:"
        gitea-client diagnose-job arcodange dance-lessons-coach $job_id
        echo "========================================"
    done
fi

# 4. Advanced monitoring with automatic diagnosis
WORKFLOW_ID=415
TIMEOUT=300
SECONDS_ELAPSED=0

while [ $SECONDS_ELAPSED -lt $TIMEOUT ]; do
    STATUS=$(gitea-client job-status arcodange dance-lessons-coach $WORKFLOW_ID | jq -r '.status')
    CONCLUSION=$(gitea-client job-status arcodange dance-lessons-coach $WORKFLOW_ID | jq -r '.conclusion')
    
    echo "[$(date)] Status: $STATUS, Conclusion: ${CONCLUSION:-not completed}"
    
    if [[ "$CONCLUSION" == "failure" ]]; then
        echo "Workflow failed! Running automatic diagnosis..."
        gitea-client diagnose-job arcodange dance-lessons-coach $WORKFLOW_ID
        
        # Find PR and comment
        PR_NUMBER=$(gitea-client list-prs arcodange dance-lessons-coach | \
            jq -r '.[] | select(.head.ref == "feature/user-authentication-bdd") | .number')
        
        if [ -n "$PR_NUMBER" ]; then
            gitea-client comment-pr arcodange dance-lessons-coach $PR_NUMBER \
                "⚠️ CI Workflow $WORKFLOW_ID failed. See diagnosis above for details."
        fi
        break
    elif [[ "$STATUS" != "in_progress" && "$STATUS" != "waiting" ]]; then
        echo "Workflow completed with status: $STATUS"
        break
    fi
    
    sleep 30
    SECONDS_ELAPSED=$((SECONDS_ELAPSED + 30))
done
```

## 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 dance-lessons-coach \
  | 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 dance-lessons-coach $JOB_ID | jq -r '.status')

# 3. If job fails, diagnose and comment
if [ "$JOB_STATUS" = "completed" ]; then
    CONCLUSION=$(gitea-client job-status arcodange dance-lessons-coach $JOB_ID | jq -r '.conclusion')
    
    if [ "$CONCLUSION" = "failure" ]; then
        # Get detailed logs
        gitea-client job-logs arcodange dance-lessons-coach $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 dance-lessons-coach $PR_NUMBER \
            "⚠️ CI Job Failed: $JOB_ID\n\n🔍 Diagnosis:\n$ERRORS\n\n📊 Job Details: $(gitea-client job-status arcodange dance-lessons-coach $JOB_ID | jq -r '.html_url')"
    fi
fi

# 4. Success case - comment on successful build
if [ "$CONCLUSION" = "success" ]; then
    gitea-client comment-pr arcodange dance-lessons-coach $PR_NUMBER \
        "✅ CI Job Passed: $JOB_ID\n\n🎉 All checks successful!\n\n📊 Job Details: $(gitea-client job-status arcodange dance-lessons-coach $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 dance-lessons-coach 1 \
    "🎉 Comprehensive PR Summary\n\nThis PR includes CI improvements and new Gitea client skill."

# Add detailed breakdown
gitea-client comment-pr arcodange dance-lessons-coach 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 dance-lessons-coach 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 dance-lessons-coach $CURRENT_JOB > current_logs.txt
ERROR_LINE=$(grep -n "pattern docs/swagger.json" current_logs.txt | head -1)

gitea-client comment-pr arcodange dance-lessons-coach 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/dance-lessons-coach/actions/runs/{run_id}`
- Workflow: `https://gitea.arcodange.lab/arcodange/dance-lessons-coach/actions`
- PR: `https://gitea.arcodange.lab/arcodange/dance-lessons-coach/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