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

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