# 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