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

name, description, license, metadata

name	description	license	metadata
gitea-client	Gitea API client for job monitoring and PR management	MIT	author version dance-lessons-coach Team 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

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 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 for detailed guidance on discovering and exploring Gitea API endpoints using the Swagger documentation.

Commands

List Workflows

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

List available workflows for a repository.

Arguments:

• owner: Repository owner
• repo: Repository name

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

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

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 dance-lessons-coach 351 | jq '.jobs[] | "Job \(.id): \(.name) - \(.html_url)"'

Examples:

# List all jobs for workflow run 350
gitea-client list-workflow-jobs arcodange dance-lessons-coach 350

Monitor Workflow Run

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:

# 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

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:

# Diagnose failed job 759
gitea-client diagnose-job arcodange dance-lessons-coach 759

Get Recent Workflows Summary

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:

# 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

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

List Issues

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:

# 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

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:

# 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

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:

# 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

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:

# 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

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

Issue Management Workflow

# 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

# 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

Enhanced Workflow Monitoring with New Commands

Complete CI Debugging Workflow with New Commands

# 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

# 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

# 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

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

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