Gabriel Radureau
7677b86b06
Add comprehensive Gitea client skill with capabilities to: - Monitor CI/CD job status and workflows - Fetch detailed job logs and action logs - List workflow jobs to identify failures - Comment on pull requests - Save logs to files for analysis Includes: - Main client script with authentication support - Complete documentation and usage examples - Support for both GITEA_API_TOKEN and GITEA_API_TOKEN_FILE - Comprehensive error handling and workflows Enables AI agents to monitor, diagnose, and interact with Gitea Actions workflows and pull requests.
288 lines
6.5 KiB
Markdown
288 lines
6.5 KiB
Markdown
name: gitea-client
|
|
description: Gitea API client for job monitoring and PR management
|
|
|
|
# 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: https://gitea.arcodange.lab/swagger.v1.json
|
|
- Base URL: https://gitea.arcodange.lab
|
|
|
|
## 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
|
|
|
|
### 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 DanceLessonsCoach 658
|
|
|
|
# Save logs to file
|
|
gitea-client job-logs arcodange DanceLessonsCoach 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 DanceLessonsCoach 658
|
|
|
|
# Save to file for analysis
|
|
gitea-client action-logs arcodange DanceLessonsCoach 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
|
|
|
|
**Examples:**
|
|
```bash
|
|
# List all jobs for workflow run 350
|
|
gitea-client list-workflow-jobs arcodange DanceLessonsCoach 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
|
|
|
|
## 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"
|
|
```
|
|
|
|
### 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
|
|
|
|
## 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
|