arcodange/dance-lessons-coach

Fork 0

Files

Gabriel Radureau de28d8fc24

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

Details

📖 docs: add comprehensive API discovery documentation to gitea-client

2026-04-06 17:32:07 +02:00

12 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 dance-lessons-coach 5 10

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

# 3. Fetch logs for debugging
gitea-client job-logs arcodange dance-lessons-coach 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 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.

12 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

12 KiB

Raw Blame History