Gabriel Radureau
9a20b6e778
Add web UI link documentation and examples: - Document html_url field usage in responses - Add examples for opening jobs in browser - Include common URL patterns - Enhance job-status and list-workflow-jobs docs Makes it easier to navigate between CLI and web UI for better CI/CD monitoring and debugging.
328 lines
7.9 KiB
Markdown
328 lines
7.9 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
|
|
|
|
**Web UI Link:**
|
|
The response includes a `html_url` field that provides a direct link to view the job in Gitea's web interface.
|
|
|
|
**Example:**
|
|
```bash
|
|
# Get job status and extract web UI link
|
|
gitea-client job-status arcodange DanceLessonsCoach 351 | jq '.html_url'
|
|
# Output: "https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/3"
|
|
```
|
|
|
|
### 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
|
|
|
|
**Web UI Links:**
|
|
Each job in the response includes a `html_url` field for direct access to that specific job's web interface.
|
|
|
|
**Example:**
|
|
```bash
|
|
# List all jobs and extract their web UI links
|
|
gitea-client list-workflow-jobs arcodange DanceLessonsCoach 351 | jq '.jobs[] | "Job \(.id): \(.name) - \(.html_url)"'
|
|
```
|
|
|
|
**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
|
|
|
|
## Web UI Integration
|
|
|
|
All API responses include `html_url` fields that provide direct links to Gitea's web interface. Use these to:
|
|
|
|
```bash
|
|
# Get web UI link for a job
|
|
job_url=$(gitea-client job-status owner repo job_id | jq -r '.html_url')
|
|
echo "View in browser: $job_url"
|
|
|
|
# Open job directly in browser (macOS)
|
|
open $(gitea-client job-status owner repo job_id | jq -r '.html_url')
|
|
|
|
# Linux/WSL
|
|
xdg-open $(gitea-client job-status owner repo job_id | jq -r '.html_url')
|
|
```
|
|
|
|
**Common URL Patterns:**
|
|
- Job: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions/runs/{run_id}`
|
|
- Workflow: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/actions`
|
|
- PR: `https://gitea.arcodange.lab/arcodange/DanceLessonsCoach/pulls/{pr_number}`
|
|
|
|
## 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
|