dance-lessons-coach/.vibe/skills/gitea-client

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)

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

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