📝 docs: add comprehensive reference guide and update to kebab-case (related to #2)
This commit is contained in:
308
.vibe/skills/gitea-client/REFERENCE.md
Normal file
308
.vibe/skills/gitea-client/REFERENCE.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# 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 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```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 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:**
|
||||
```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 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Before commenting, verify job status
|
||||
gitea-client job-status arcodange DanceLessonsCoach 706
|
||||
```
|
||||
|
||||
### 2. Use Descriptive Issue Titles
|
||||
```bash
|
||||
# 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
|
||||
```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 DanceLessonsCoach 15 "See: https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/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 DanceLessonsCoach \
|
||||
"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 DanceLessonsCoach 706 job_706_$(date +%Y%m%d).txt
|
||||
```
|
||||
|
||||
### 2. Monitor Job Progress
|
||||
```bash
|
||||
watch -n 10 "gitea-client job-status arcodange DanceLessonsCoach 706"
|
||||
```
|
||||
|
||||
### 3. Script Complex Workflows
|
||||
```bash
|
||||
#!/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.
|
||||
@@ -95,7 +95,7 @@ cmd_job_logs() {
|
||||
exit 1
|
||||
fi
|
||||
|
||||
local endpoint="/repos/${owner}/${repo}/actions/runs/${job_id}/logs"
|
||||
local endpoint="/repos/${owner}/${repo}/actions/jobs/${job_id}/logs"
|
||||
local logs=$(api_request "GET" "$endpoint")
|
||||
|
||||
if [[ -n "$output_file" ]]; then
|
||||
|
||||
@@ -124,14 +124,34 @@ gitea-client create-issue arcodange DanceLessonsCoach "Issue Title" "Detailed de
|
||||
**Commit:** `a5f652f`
|
||||
**Message:** `🔧 refactor: replace 4 workflows with single optimized ci-cd.yaml (related to #2)`
|
||||
|
||||
**Web UI:** https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/issues/2
|
||||
**Web UI:** https://gitea.arcodange.lab/arcodange/dance-lessons-coach/issues/2
|
||||
|
||||
**Validation Workflow:**
|
||||
- **Run ID:** 365
|
||||
- **Status:** in_progress
|
||||
- **URL:** https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/17
|
||||
- **URL:** https://gitea.arcodange.lab/arcodange/dance-lessons-coach/actions/runs/17
|
||||
- **Workflow:** ci-cd.yaml (single unified workflow)
|
||||
|
||||
### Project Renaming
|
||||
|
||||
**Change:** Updated git remote to use kebab-case
|
||||
|
||||
**Before:**
|
||||
```
|
||||
ssh://git@192.168.1.202:2222/arcodange/DanceLessonsCoach.git
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
ssh://git@192.168.1.202:2222/arcodange/dance-lessons-coach.git
|
||||
```
|
||||
|
||||
**Impact:**
|
||||
- ✅ Repository URL now uses kebab-case (hyphen-separated)
|
||||
- ✅ Matches modern naming conventions
|
||||
- ✅ Consistent with Gitea server configuration
|
||||
- ✅ No functional changes (same repository, new URL)
|
||||
|
||||
### TRUE Workflow Optimization (Replaced 4 workflows with 1)
|
||||
|
||||
**Problem Identified:**
|
||||
@@ -202,6 +222,26 @@ gitea-client create-issue arcodange DanceLessonsCoach "Issue Title" "Detailed de
|
||||
- ✅ Easier to reference skills
|
||||
- ✅ Better organization
|
||||
|
||||
### Comprehensive Reference Guide
|
||||
|
||||
**Created:** `.vibe/skills/gitea-client/REFERENCE.md`
|
||||
|
||||
**Content:**
|
||||
- 📋 Job monitoring use cases
|
||||
- 🔧 PR management examples
|
||||
- 📝 Issue tracking workflows
|
||||
- 🎯 Real-world scenarios with copy-paste commands
|
||||
- 🔧 Advanced patterns and best practices
|
||||
- 📋 Complete command reference table
|
||||
|
||||
**Purpose:**
|
||||
- ✅ Onboard new developers quickly
|
||||
- ✅ Provide real-world examples
|
||||
- ✅ Document best practices
|
||||
- ✅ Serve as living documentation
|
||||
|
||||
**Size:** 9.1KB of comprehensive documentation
|
||||
|
||||
**Validation Status:** ⏳ IN PROGRESS
|
||||
- ✅ Commit pushed: `a5f652f`
|
||||
- ✅ Single workflow triggered: Run #365
|
||||
|
||||
10
README.md
10
README.md
@@ -1,8 +1,8 @@
|
||||
# DanceLessonsCoach
|
||||
|
||||
[](https://gitea.arcodange.fr/arcodange/DanceLessonsCoach)
|
||||
[](https://goreportcard.com/report/github.com/arcodange/DanceLessonsCoach)
|
||||
[](https://gitea.arcodange.fr/arcodange/DanceLessonsCoach/releases)
|
||||
[](https://gitea.arcodange.fr/arcodange/dance-lessons-coach)
|
||||
[](https://goreportcard.com/report/github.com/arcodange/dance-lessons-coach)
|
||||
[](https://gitea.arcodange.fr/arcodange/dance-lessons-coach/releases)
|
||||
[](LICENSE)
|
||||
|
||||
A Go project demonstrating idiomatic package structure, CLI implementation, and JSON API with Chi router.
|
||||
@@ -27,8 +27,8 @@ A Go project demonstrating idiomatic package structure, CLI implementation, and
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/yourusername/DanceLessonsCoach.git
|
||||
cd DanceLessonsCoach
|
||||
git clone https://gitea.arcodange.lab/arcodange/dance-lessons-coach.git
|
||||
cd dance-lessons-coach
|
||||
|
||||
# Build all binaries
|
||||
./scripts/build.sh
|
||||
|
||||
Reference in New Issue
Block a user