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.
138 lines
3.3 KiB
Markdown
138 lines
3.3 KiB
Markdown
# Gitea Client Skill - Setup Guide
|
|
|
|
This guide explains how to set up and use the Gitea Client skill for AI agent integration.
|
|
|
|
## Prerequisites
|
|
|
|
1. **Gitea Account**: You need access to the Gitea instance at https://gitea.arcodange.lab
|
|
2. **Personal Access Token**: Create a token with appropriate permissions
|
|
3. **curl and jq**: Required for API interactions
|
|
|
|
## Setup Instructions
|
|
|
|
### 1. Create a Personal Access Token
|
|
|
|
1. Log in to https://gitea.arcodange.lab
|
|
2. Go to your profile → Settings → Applications
|
|
3. Click "Generate New Token"
|
|
4. Set required scopes:
|
|
- `read:repository` - Read repository data
|
|
- `write:repository` - Comment on PRs
|
|
- `read:user` - Read user data
|
|
5. Copy the generated token
|
|
|
|
### 2. Configure Authentication
|
|
|
|
**Option A: Environment Variable (Simple)**
|
|
```bash
|
|
export GITEA_API_TOKEN="your_personal_access_token"
|
|
```
|
|
|
|
**Option B: Token File (Recommended for security)**
|
|
```bash
|
|
echo "your_personal_access_token" > ~/.gitea_token
|
|
chmod 600 ~/.gitea_token
|
|
export GITEA_API_TOKEN_FILE="$HOME/.gitea_token"
|
|
```
|
|
|
|
### 3. Add to Your Shell Configuration
|
|
|
|
Add the export command to your `~/.bashrc`, `~/.zshrc`, or equivalent:
|
|
|
|
```bash
|
|
# For environment variable
|
|
echo 'export GITEA_API_TOKEN="your_token"' >> ~/.bashrc
|
|
|
|
# For token file
|
|
echo 'export GITEA_API_TOKEN_FILE="$HOME/.gitea_token"' >> ~/.bashrc
|
|
```
|
|
|
|
Then reload your shell:
|
|
```bash
|
|
source ~/.bashrc
|
|
```
|
|
|
|
## Usage Examples
|
|
|
|
### Test Your Setup
|
|
|
|
```bash
|
|
# List recent jobs for a workflow
|
|
./scripts/gitea-client.sh list-jobs owner repo workflow_id 5
|
|
|
|
# Check job status
|
|
./scripts/gitea-client.sh job-status owner repo job_id
|
|
```
|
|
|
|
### Monitor a CI/CD Job
|
|
|
|
```bash
|
|
# Wait for job completion (5 minute timeout)
|
|
./scripts/gitea-client.sh wait-job owner repo job_id 300
|
|
|
|
# Get logs if failed
|
|
./scripts/gitea-client.sh job-logs owner repo job_id
|
|
```
|
|
|
|
### Comment on a Pull Request
|
|
|
|
```bash
|
|
# Add a comment to PR #42
|
|
./scripts/gitea-client.sh comment-pr owner repo 42 "Build completed successfully!"
|
|
|
|
# Get PR status
|
|
./scripts/gitea-client.sh pr-status owner repo 42
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
**401 Unauthorized**
|
|
- Check your token is correct
|
|
- Verify token has required scopes
|
|
- Ensure you're using the right authentication method
|
|
|
|
**404 Not Found**
|
|
- Verify repository owner and name
|
|
- Check workflow ID and job ID
|
|
- Confirm PR number exists
|
|
|
|
**429 Too Many Requests**
|
|
- Wait and retry
|
|
- Consider rate limiting in your scripts
|
|
- Contact admin if this persists
|
|
|
|
### Debugging
|
|
|
|
Enable verbose output by modifying the script:
|
|
```bash
|
|
# Change this line in gitea-client.sh
|
|
curl -s ... # Remove -s for verbose output
|
|
curl ... # Shows full request/response
|
|
```
|
|
|
|
## Security Best Practices
|
|
|
|
1. **Never commit tokens to version control**
|
|
2. **Use token files with restrictive permissions** (`chmod 600`)
|
|
3. **Rotate tokens regularly**
|
|
4. **Use minimal required scopes**
|
|
5. **Revoke tokens when no longer needed**
|
|
|
|
## API Documentation
|
|
|
|
- **Swagger**: https://gitea.arcodange.lab/swagger.v1.json
|
|
- **Gitea API Docs**: https://docs.gitea.com/api/usage
|
|
|
|
## Support
|
|
|
|
For issues with the Gitea instance:
|
|
- Contact: system administrators
|
|
- Instance: https://gitea.arcodange.lab
|
|
|
|
For issues with this skill:
|
|
- Check the SKILL.md for command reference
|
|
- Review this README for setup
|
|
- Examine the script for implementation details
|