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

export GITEA_API_TOKEN="your_personal_access_token"

Option 2: Token File (Recommended for security)

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

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

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:

# 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

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:

# 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

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:

# 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

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:

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

# List all jobs for workflow run 350
gitea-client list-workflow-jobs arcodange DanceLessonsCoach 350

Wait for Job Completion

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

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

# 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