arcodange/dance-lessons-coach

Fork 0

Files

Gabriel Radureau e21b81baef

CI/CD Pipeline / CI Pipeline (push) Has been cancelled

Details

📖 docs: add comprehensive reference guide and update to kebab-case (related to #2 )

2026-04-06 17:18:31 +02:00

9.1 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 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]

Example Workflow:

# 1. Find recent failed jobs
gitea-client list-jobs arcodange DanceLessonsCoach 5 10

# 2. Check status of specific job
gitea-client job-status arcodange DanceLessonsCoach 706

# 3. Fetch logs for debugging
gitea-client job-logs arcodange DanceLessonsCoach 706 job_706_logs.txt

# 4. Analyze logs
grep -i "error\|fail" job_706_logs.txt

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 DanceLessonsCoach | jq -r '.[] | select(.head.ref == "feature/new-feature") | .number')

# Comment on PR with CI results
gitea-client comment-pr arcodange DanceLessonsCoach $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 DanceLessonsCoach "CI Failure" "Workflow failed on job 706"

# Add progress comment
gitea-client comment-issue arcodange DanceLessonsCoach 42 "Investigating logs..."

# Resolve issue
gitea-client comment-issue arcodange DanceLessonsCoach 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 DanceLessonsCoach 5 5

# 2. Find failed job
gitea-client job-status arcodange DanceLessonsCoach 706

# 3. Fetch logs
gitea-client job-logs arcodange DanceLessonsCoach 706 debug_logs.txt

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

# 5. Comment on related PR
gitea-client comment-pr arcodange DanceLessonsCoach 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 DanceLessonsCoach | jq -r '.[] | select(.head.ref == "feature/new-api") | .number')

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

🔍 Errors found:
$ERRORS

📊 Job Details: https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/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 DanceLessonsCoach "Add user authentication" "Implement OAuth2 authentication for API"

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

# 3. Complete feature
gitea-client comment-issue arcodange DanceLessonsCoach 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 DanceLessonsCoach $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 DanceLessonsCoach \
        "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 DanceLessonsCoach $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 DanceLessonsCoach 706

2. Use Descriptive Issue Titles

# Good
gitea-client create-issue arcodange DanceLessonsCoach "API Authentication Failure" "Detailed description..."

# Bad
gitea-client create-issue arcodange DanceLessonsCoach "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 DanceLessonsCoach 15 "See: https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/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 DanceLessonsCoach \
        "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 DanceLessonsCoach 706 job_706_$(date +%Y%m%d).txt

2. Monitor Job Progress

watch -n 10 "gitea-client job-status arcodange DanceLessonsCoach 706"

3. Script Complex Workflows

#!/bin/bash
# monitor_and_comment.sh
JOB_ID=$1
PR_NUMBER=$2

STATUS=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.status')
if [ "$STATUS" = "completed" ]; then
    CONCLUSION=$(gitea-client job-status arcodange DanceLessonsCoach $JOB_ID | jq -r '.conclusion')
    if [ "$CONCLUSION" = "failure" ]; then
        gitea-client job-logs arcodange DanceLessonsCoach $JOB_ID logs.txt
        ERRORS=$(grep -i "error" logs.txt | head -3)
        gitea-client comment-pr arcodange DanceLessonsCoach $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>`

🎓 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, and issue tracking with practical, copy-paste-ready examples.

9.1 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

🎓 Learning Resources

9.1 KiB

Raw Blame History