arcodange/dance-lessons-coach

Fork 0

Files

Gabriel Radureau 52065c9cf3

CI/CD Pipeline / Build Docker Cache (push) Successful in 10s

Details

CI/CD Pipeline / CI Pipeline (push) Failing after 13s

Details

✨ refactor: convert all DanceLessonsCoach mentions to kebab-case

2026-04-07 19:11:39 +02:00

16 KiB

Raw Blame History

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:

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

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

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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Before commenting, verify job status
gitea-client job-status arcodange dance-lessons-coach 706

2. Use Descriptive Issue Titles

# 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

# Link commits to issues
git commit -m "🐛 fix: resolve auth bug (closes #42)"

4. Use Web UI Links

# 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

# 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

# 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

gitea-client job-logs arcodange dance-lessons-coach 706 job_706_$(date +%Y%m%d).txt

2. Monitor Job Progress

watch -n 10 "gitea-client job-status arcodange dance-lessons-coach 706"

3. Script Complex Workflows

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

# 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

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

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

Find issue-related endpoints:

curl -s https://gitea.arcodange.lab/swagger.v1.json | \
  jq '.paths | with_entries(select(.key | contains("issues"))) | keys'

Get endpoint parameters and responses:

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:

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

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

# 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

# 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

# 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

16 KiB Raw Blame History

Gitea-Client Skill Reference Guide

🎯 Overview

📋 Use Cases

1. Job Monitoring and CI/CD Management

2. Pull Request Management

3. Issue Tracking

🎯 Real-World Examples

Example 1: CI/CD Debugging Workflow

Example 2: Automated PR Feedback

Example 3: Issue Management Workflow

🔧 Advanced Patterns

Monitoring Multiple Jobs

Automated Issue Creation

Batch Issue Updates

📖 Best Practices

1. Always Check Job Status First

2. Use Descriptive Issue Titles

3. Reference Issues in Commits

4. Use Web UI Links

🎯 Integration Patterns

CI/CD Pipeline Integration

Automated Issue Tracking

💡 Tips and Tricks

1. Save Logs for Later Analysis

2. Monitor Job Progress

3. Script Complex Workflows

🔗 API Reference

📋 Command Reference

🔍 Discovering Gitea API Endpoints

Using Swagger Documentation

Exploring Actions API

Practical API Discovery Examples

API Documentation Structure

Common Endpoint Patterns

Discovering New Features

🎓 Learning Resources

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

CI/CD Pipeline Debugging

Automated CI Monitoring

PR Management Automation

16 KiB

Raw Blame History