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

# Gitea-Client Skill Reference Guide

## 🎯 Overview

The Gitea-Client skill provides comprehensive API access to Gitea repositories, enabling job monitoring, PR management, and issue tracking directly from the command line.

## 📋 Use Cases

### 1. Job Monitoring and CI/CD Management

**Scenario:** Monitor CI/CD workflows and diagnose failures

**Commands:**
```bash
# List available workflows
gitea-client list-workflows <owner> <repo>

# List recent workflow jobs
gitea-client list-jobs <owner> <repo> <workflow_id> [limit]

# Check specific job status
gitea-client job-status <owner> <repo> <job_id>

# Fetch job logs for debugging
gitea-client job-logs <owner> <repo> <job_id> [output_file]

# List all jobs in a workflow run
gitea-client list-workflow-jobs <owner> <repo> <workflow_run_id>

# Wait for job completion
gitea-client wait-job <owner> <repo> <job_id> [timeout]

# Monitor workflow run until completion (with automatic updates)
gitea-client monitor-workflow <owner> <repo> <workflow_run_id> [interval_seconds]

# Diagnose failed job with automatic error analysis
gitea-client diagnose-job <owner> <repo> <job_id>

# Get summary of recent workflow runs
gitea-client recent-workflows <owner> <repo> [limit] [status_filter]
```

**Example Workflow:**
```bash
# 1. Get summary of recent workflows
gitea-client recent-workflows arcodange dance-lessons-coach 5

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

# 3. Diagnose a failed job automatically
gitea-client diagnose-job arcodange dance-lessons-coach 759

# 4. List available workflows to get workflow IDs
gitea-client list-workflows arcodange dance-lessons-coach

# 5. Check status of specific job
gitea-client job-status arcodange dance-lessons-coach 706

# 6. Fetch logs for debugging
gitea-client job-logs arcodange dance-lessons-coach 706 job_706_logs.txt

# 7. Analyze logs manually
grep -i "error\|fail" job_706_logs.txt
```

**Advanced Monitoring Example:**
```bash
# Monitor workflow and automatically diagnose if it fails
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 "Job failed! Running diagnosis..."
        gitea-client diagnose-job arcodange dance-lessons-coach $WORKFLOW_ID
        break
    elif [[ "$STATUS" != "in_progress" && "$STATUS" != "waiting" ]]; then
        echo "Job completed with status: $STATUS"
        break
    fi
    
    sleep 30
    SECONDS_ELAPSED=$((SECONDS_ELAPSED + 30))
done
```

### 2. Pull Request Management

**Scenario:** Monitor and comment on PRs during CI/CD

**Commands:**
```bash
# Check PR status
gitea-client pr-status <owner> <repo> <pr_number>

# Add comment to PR
gitea-client comment-pr <owner> <repo> <pr_number> <comment>
```

**Example Workflow:**
```bash
# Get PR number from branch
PR_NUMBER=$(gitea-client list-prs arcodange dance-lessons-coach | jq -r '.[] | select(.head.ref == "feature/new-feature") | .number')

# Comment on PR with CI results
gitea-client comment-pr arcodange dance-lessons-coach $PR_NUMBER "✅ CI passed: All checks successful!"
```

### 3. Issue Tracking

**Scenario:** Create and manage repository issues

**Commands:**
```bash
# List open issues
gitea-client list-issues <owner> <repo> [state]

# Create new issue
gitea-client create-issue <owner> <repo> <title> <description>

# Show issue details
gitea-client show-issue <owner> <repo> <issue_number>

# Comment on issue
gitea-client comment-issue <owner> <repo> <issue_number> <comment>
```

**Example Workflow:**
```bash
# Create issue for bug
gitea-client create-issue arcodange dance-lessons-coach "CI Failure" "Workflow failed on job 706"

# Add progress comment
gitea-client comment-issue arcodange dance-lessons-coach 42 "Investigating logs..."

# Resolve issue
gitea-client comment-issue arcodange dance-lessons-coach 42 "✅ Fixed in commit abc123"
```

## 🎯 Real-World Examples

### Example 1: CI/CD Debugging Workflow

```bash
# Scenario: Job failed, need to diagnose

# 1. List recent jobs
gitea-client list-jobs arcodange dance-lessons-coach 5 5

# 2. Find failed job
gitea-client job-status arcodange dance-lessons-coach 706

# 3. Fetch logs
gitea-client job-logs arcodange dance-lessons-coach 706 debug_logs.txt

# 4. Analyze
grep -i "error\|panic\|fail" debug_logs.txt

# 5. Comment on related PR
gitea-client comment-pr arcodange dance-lessons-coach 15 "Found issue in CI - investigating"
```

### Example 2: Automated PR Feedback

```bash
# Scenario: CI job failed, auto-comment on PR

JOB_ID=706
PR_NUMBER=$(gitea-client list-prs arcodange dance-lessons-coach | jq -r '.[] | select(.head.ref == "feature/new-api") | .number')

if [ -n "$PR_NUMBER" ]; then
    gitea-client job-logs arcodange dance-lessons-coach $JOB_ID job_logs.txt
    ERRORS=$(grep -i "error\|fail" job_logs.txt | head -5)
    
    gitea-client comment-pr arcodange dance-lessons-coach $PR_NUMBER "⚠️ CI Job Failed: $JOB_ID

🔍 Errors found:
$ERRORS

📊 Job Details: https://gitea.arcodange.lab/arcodange/dance-lessons-coach/actions/runs/17/jobs/0"
fi
```

### Example 3: Issue Management Workflow

```bash
# Scenario: Feature implementation with issue tracking

# 1. Create issue for new feature
gitea-client create-issue arcodange dance-lessons-coach "Add user authentication" "Implement OAuth2 authentication for API"

# 2. Work on feature, add progress comments
gitea-client comment-issue arcodange dance-lessons-coach 42 "⏳ IN PROGRESS: Implementing OAuth2 provider"

# 3. Complete feature
gitea-client comment-issue arcodange dance-lessons-coach 42 "✅ COMPLETED: Authentication implemented in commit abc123"

# 4. Reference in commit
git commit -m "✨ feat: add OAuth2 authentication (closes #42)"
```

## 🔧 Advanced Patterns

### Monitoring Multiple Jobs

```bash
# Watch multiple jobs in parallel
for job_id in 706 707 708; do
    gitea-client job-status arcodange dance-lessons-coach $job_id &
done
wait
```

### Automated Issue Creation

```bash
# Create issue from CI when tests fail
if [ "$CI_JOB_STATUS" = "failed" ]; then
    gitea-client create-issue arcodange dance-lessons-coach \
        "CI Failure: $CI_JOB_NAME" \
        "Job failed on commit $CI_COMMIT_SHA. See logs: $CI_JOB_URL"
fi
```

### Batch Issue Updates

```bash
# Update multiple issues with same comment
for issue in 42 43 44; do
    gitea-client comment-issue arcodange dance-lessons-coach $issue "Status update: Related to PR #15"
done
```

## 📖 Best Practices

### 1. Always Check Job Status First
```bash
# Before commenting, verify job status
gitea-client job-status arcodange dance-lessons-coach 706
```

### 2. Use Descriptive Issue Titles
```bash
# Good
gitea-client create-issue arcodange dance-lessons-coach "API Authentication Failure" "Detailed description..."

# Bad
gitea-client create-issue arcodange dance-lessons-coach "Bug" "Doesn't work"
```

### 3. Reference Issues in Commits
```bash
# Link commits to issues
git commit -m "🐛 fix: resolve auth bug (closes #42)"
```

### 4. Use Web UI Links
```bash
# Include links in comments
gitea-client comment-pr arcodange dance-lessons-coach 15 "See: https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/42"
```

## 🎯 Integration Patterns

### CI/CD Pipeline Integration

```yaml
# Example GitHub Actions step
- name: Comment on PR if tests fail
  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
```

### Automated Issue Tracking

```bash
# Script to create issues from errors
ERRORS=$(grep -i "error" app.log | head -5)
if [ -n "$ERRORS" ]; then
    gitea-client create-issue arcodange dance-lessons-coach \
        "Production Errors Detected" \
        "Found errors in production logs:\n\n$ERRORS"
fi
```

## 💡 Tips and Tricks

### 1. Save Logs for Later Analysis
```bash
gitea-client job-logs arcodange dance-lessons-coach 706 job_706_$(date +%Y%m%d).txt
```

### 2. Monitor Job Progress
```bash
watch -n 10 "gitea-client job-status arcodange dance-lessons-coach 706"
```

### 3. Script Complex Workflows
```bash
#!/bin/bash
# monitor_and_comment.sh
JOB_ID=$1
PR_NUMBER=$2

STATUS=$(gitea-client job-status arcodange dance-lessons-coach $JOB_ID | jq -r '.status')
if [ "$STATUS" = "completed" ]; then
    CONCLUSION=$(gitea-client job-status arcodange dance-lessons-coach $JOB_ID | jq -r '.conclusion')
    if [ "$CONCLUSION" = "failure" ]; then
        gitea-client job-logs arcodange dance-lessons-coach $JOB_ID logs.txt
        ERRORS=$(grep -i "error" logs.txt | head -3)
        gitea-client comment-pr arcodange dance-lessons-coach $PR_NUMBER "❌ Job failed: $ERRORS"
    fi
fi
```

## 🔗 API Reference

All commands use the Gitea REST API v1:
- **Base URL**: `https://gitea.arcodange.lab/api/v1`
- **Authentication**: Personal Access Token (required)
- **Documentation**: https://gitea.com/api/swagger

## 📋 Command Reference

| Command | Description | Usage |
|---------|-------------|-------|
| `list-jobs` | List workflow jobs | `gitea-client list-jobs <owner> <repo> <workflow_id> [limit]` |
| `job-status` | Get job status | `gitea-client job-status <owner> <repo> <job_id>` |
| `job-logs` | Fetch job logs | `gitea-client job-logs <owner> <repo> <job_id> [output_file]` |
| `list-workflow-jobs` | List jobs in workflow | `gitea-client list-workflow-jobs <owner> <repo> <workflow_run_id>` |
| `wait-job` | Wait for job completion | `gitea-client wait-job <owner> <repo> <job_id> [timeout]` |
| `comment-pr` | Comment on PR | `gitea-client comment-pr <owner> <repo> <pr_number> <comment>` |
| `pr-status` | Get PR status | `gitea-client pr-status <owner> <repo> <pr_number>` |
| `list-issues` | List repository issues | `gitea-client list-issues <owner> <repo> [state]` |
| `create-issue` | Create new issue | `gitea-client create-issue <owner> <repo> <title> <description>` |
| `show-issue` | Show issue details | `gitea-client show-issue <owner> <repo> <issue_number>` |
| `comment-issue` | Comment on issue | `gitea-client comment-issue <owner> <repo> <issue_number> <comment>` |

## 🔍 Discovering Gitea API Endpoints

### Using Swagger Documentation

The Gitea API provides comprehensive Swagger/OpenAPI documentation that you can use to discover available endpoints:

```bash
# Fetch the complete Swagger JSON
curl -s https://gitea.arcodange.lab/swagger.v1.json > gitea_api.json

# List all available endpoints
jq '.paths | keys' gitea_api.json

# Find Actions/CI/CD related endpoints
jq '.paths | with_entries(select(.key | contains("actions"))) | keys' gitea_api.json

# Get details about a specific endpoint
jq '.paths["/repos/{owner}/{repo}/actions/runs"]' gitea_api.json
```

### Exploring Actions API

```bash
# List all Actions-related endpoints
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths | with_entries(select(.key | contains("actions"))) | keys'

# Check available methods for workflow runs endpoint
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths["/repos/{owner}/{repo}/actions/runs/{run}"] | keys'

# Check available methods for jobs endpoint  
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths["/repos/{owner}/{repo}/actions/jobs/{job_id}"] | keys'
```

### Practical API Discovery Examples

**Find all repository endpoints:**
```bash
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths | with_entries(select(.key | startswith("/repos/"))) | keys | length'
```

**Find issue-related endpoints:**
```bash
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths | with_entries(select(.key | contains("issues"))) | keys'
```

**Get endpoint parameters and responses:**
```bash
curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths["/repos/{owner}/{repo}/actions/runs"] | .get | {parameters, responses}'
```

### API Documentation Structure

The Gitea Swagger documentation follows this structure:

```json
{
  "paths": {
    "/endpoint/path": {
      "get": {
        "tags": ["category"],
        "summary": "Endpoint description",
        "parameters": [...],
        "responses": {...}
      },
      "post": {...},
      "delete": {...}
    }
  },
  "definitions": {...},
  "responses": {...}
}
```

### Common Endpoint Patterns

- **Repository actions**: `/repos/{owner}/{repo}/actions/*`
- **Organization actions**: `/orgs/{org}/actions/*`
- **User actions**: `/user/actions/*`
- **Admin actions**: `/admin/actions/*`

### Discovering New Features

When Gitea adds new features, check the Swagger documentation first:

```bash
# Compare with official Gitea documentation
curl -s https://try.gitea.io/swagger.v1.json | \
  jq '.paths | length'  # Official Gitea instance

curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths | length'  # Your instance
```

## 🎓 Learning Resources

- **Gitea API Docs**: https://gitea.com/api/swagger
- **GitHub Actions**: https://docs.github.com/en/actions
- **JQ Tutorial**: https://stedolan.github.io/jq/manual/

This reference guide provides comprehensive examples for using the gitea-client skill in real-world scenarios, covering job monitoring, PR management, issue tracking, and API discovery with practical, copy-paste-ready examples.

## 🎯 Real-World Use Cases from dance-lessons-coach

### CI/CD Pipeline Debugging

**Scenario**: TLS certificate verification failures were blocking all CI/CD progress.

**Solution**: Replaced Docker Buildx with traditional docker build + push.

```bash
# Before (Failed)
# ERROR: failed to build: failed to solve: failed to push
# tls: failed to verify certificate: x509: certificate signed by unknown authority

# After (Working)
gitea-client diagnose-job arcodange dance-lessons-coach 766
# Result: Building cache image: gitea.arcodange.lab/... (no TLS errors)

# Monitor the fix
gitea-client monitor-workflow arcodange dance-lessons-coach 418 30
```

### Automated CI Monitoring

```bash
# Monitor workflow and auto-diagnose failures
WORKFLOW_ID=418
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 diagnosis..."
        gitea-client diagnose-job arcodange dance-lessons-coach $WORKFLOW_ID
        break
    elif [[ "$STATUS" != "in_progress" && "$STATUS" != "waiting" ]]; then
        echo "✅ Workflow completed: $STATUS"
        break
    fi
    
    sleep 30
    SECONDS_ELAPSED=$((SECONDS_ELAPSED + 30))
done
```

### PR Management Automation

```bash
# Automated PR triage based on CI results
OPEN_PRS=$(gitea-client list-prs arcodange dance-lessons-coach | jq -r '.[] | select(.state == "open") | .number')

for pr in $OPEN_PRS; do
    PR_DETAILS=$(gitea-client pr-status arcodange dance-lessons-coach $pr)
    BRANCH=$(echo "$PR_DETAILS" | jq -r '.head.ref')
    
    # Find related workflows
    WORKFLOWS=$(gitea-client recent-workflows arcodange dance-lessons-coach 5 | grep "$BRANCH" || echo "")
    
    if [ -n "$WORKFLOWS" ]; then
        LATEST_WORKFLOW=$(echo "$WORKFLOWS" | head -1 | cut -d':' -f1)
        CONCLUSION=$(gitea-client job-status arcodange dance-lessons-coach $LATEST_WORKFLOW | jq -r '.conclusion')
        
        if [ "$CONCLUSION" = "failure" ]; then
            gitea-client comment-pr arcodange dance-lessons-coach $pr "⚠️ CI Failed - Check workflow $LATEST_WORKFLOW"
        elif [ "$CONCLUSION" = "success" ]; then
            gitea-client comment-pr arcodange dance-lessons-coach $pr "✅ CI Passed - Ready for review!"
        fi
    fi
done
```