Gabriel Radureau
99b2e410f2
Cut AGENTS.md from 1296 to ~210 lines: removed development timeline, changelog, stale AI agent section, verbose architecture examples, and duplicate content. Kept tech stack, project structure, key commands, config reference, API table, ADR index, and commit conventions. Cut README.md from 423 to ~80 lines: removed duplicate CI/CD sections (one had merge conflict markers), non-existent Cobra CLI and documentation/ references, and the AI agent usage section. Kept features, quick start, config table, API table, testing, and Gitea client setup. Also includes gitea-client.sh fixes from earlier session: create-pr sub-command and safe jq-based JSON body in comment-pr. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Gitea Client Skill - Setup Guide
This guide explains how to set up and use the Gitea Client skill for AI agent integration.
Prerequisites
- Gitea Account: You need access to the Gitea instance at https://gitea.arcodange.lab
- Personal Access Token: Create a token with appropriate permissions
- curl and jq: Required for API interactions
Setup Instructions
1. Create a Personal Access Token
- Log in to https://gitea.arcodange.lab
- Go to your profile → Settings → Applications
- Click "Generate New Token"
- Set required scopes:
read:repository- Read repository datawrite:repository- Comment on PRsread:user- Read user data
- Copy the generated token
2. Configure Authentication
Option A: Environment Variable (Simple)
export GITEA_API_TOKEN="your_personal_access_token"
Option B: Token File (Recommended for security)
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:
# 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:
source ~/.bashrc
Usage Examples
Test Your Setup
# 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
# 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
# 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:
# Change this line in gitea-client.sh
curl -s ... # Remove -s for verbose output
curl ... # Shows full request/response
Security Best Practices
- Never commit tokens to version control
- Use token files with restrictive permissions (
chmod 600) - Rotate tokens regularly
- Use minimal required scopes
- 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