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

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

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