# Gitea Basics for LLMs

**Purpose**: Core concepts and features of Gitea that LLMs should understand when working with Gitea-based projects.

**Reference**: [Gitea Official Documentation](https://docs.gitea.com/)

---

## What is Gitea?

Gitea is a **painless, self-hosted, all-in-one software development service**. It includes:

- Git hosting and repository management
- Code review (Pull Requests and AGit workflow)
- Issue tracking and project management
- CI/CD via Gitea Actions (compatible with GitHub Actions)
- Package registry (20+ package types: Cargo, npm, PyPI, Maven, etc.)
- Team collaboration tools

**Key Point**: Gitea is similar to GitHub, Bitbucket, and GitLab, but is designed to be lightweight and self-hosted.

---

## Core Features

### 1. Code Hosting

- Create and manage repositories
- Browse commit history and code files
- Review and merge code submissions
- Manage collaborators
- Handle branches, tags, cherry-picking, hooks
- Integrated collaboration tools

### 2. Code Review

- **Pull Request workflow** (same as GitHub)
- **AGit workflow** (Gitea-specific alternative)
- Online code browsing
- Review comments and feedback
- Inline code modifications

### 3. Issue Tracking

- Track requirements, features, and bugs
- Support for branches, tags, milestones
- Assignments, time tracking, due dates
- Dependencies between issues
- Project columns and boards

### 4. CI/CD (Gitea Actions)

- **Compatible with GitHub Actions**
- Write workflows in YAML format
- Reuse existing Actions plugins
- Actions plugins can be downloaded from any Git website
- Same `.github/workflows/` directory structure

### 5. Package Registry

Supports 20+ package types:
- Cargo, Chef, Composer, Conan, Conda
- Container, Helm, Maven, npm, NuGet
- Pub, PyPI, RubyGems, Vagrant
- And more

### 6. Security

- User permission management
- Access control lists (ACLs)
- Security-focused design
- Non-root system account recommended

---

## System Requirements

- **Minimum**: Raspberry Pi 3 (for small workloads)
- **Typical**: 2 CPU cores, 1GB RAM (for small teams/projects)
- **Git**: Version 2.0.0 or later required
- **Platforms**: Linux, macOS, Windows (x86, amd64, ARM, PowerPC)

---

## Key Differences from GitHub

### 1. Self-Hosted

- Runs on your own infrastructure
- Full control over data and access
- No dependency on external services
- Can be air-gapped if needed

### 2. Lightweight

- Designed to be fast and resource-efficient
- Suitable for resource-limited environments
- Lower system requirements than GitHub/GitLab

### 3. Open Source

- MIT licensed
- Community-driven development
- Transparent codebase
- No vendor lock-in

### 4. Actions Compatibility

- Gitea Actions uses same format as GitHub Actions
- Workflows are largely interchangeable
- Some GitHub-specific features may not be available
- Actions can be sourced from any Git repository

### 5. API Differences

- Gitea API is similar to GitHub's but not identical
- Some endpoints may differ
- Authentication methods are similar
- Webhook formats are compatible

---

## Terminology

### Same as GitHub

- **Repository** / **Repo** - Code storage
- **Branch** - Code versioning
- **Pull Request** / **PR** - Code review request
- **Issue** - Bug/feature tracking
- **Commit** - Code change
- **Tag** - Release marker
- **Fork** - Copy of repository
- **Clone** - Local copy

### Gitea-Specific

- **AGit workflow** - Alternative to Pull Request workflow
- **Gitea Actions** - CI/CD system (compatible with GitHub Actions)
- **Self-hosted** - Running on your own infrastructure

---

## Common Workflows

### Creating a Repository

1. Log in to Gitea instance
2. Click "New Repository"
3. Configure repository settings
4. Push code or initialize with README

### Creating a Pull Request

1. Create a branch
2. Make changes and commit
3. Push branch to Gitea
4. Click "New Pull Request"
5. Review and merge (same as GitHub)

### Using Gitea Actions

1. Create `.github/workflows/` directory
2. Write workflow YAML (same format as GitHub Actions)
3. Push to repository
4. Gitea Actions will execute workflows

### Managing Issues

1. Create issue from repository
2. Assign to team members
3. Link to milestones, labels, projects
4. Track dependencies and due dates

---

## For LLMs: Important Notes

### When Documenting

- Always refer to "Gitea" (not "GitHub") when the platform is Gitea
- Note that Gitea Actions is compatible with GitHub Actions
- Use Gitea terminology consistently
- Link to Gitea documentation: `https://docs.gitea.com/`

### When Creating Workflows

- Use `.github/workflows/` directory (same as GitHub)
- YAML format is identical to GitHub Actions
- Reference as "Gitea Actions workflows"
- Note compatibility in documentation

### When Working with API

- Gitea API is similar but not identical to GitHub's
- Check Gitea API documentation for specific endpoints
- Authentication uses tokens (similar to GitHub)
- Webhooks are compatible

---

## References

- **Gitea Documentation**: https://docs.gitea.com/
- **Gitea Features**: https://docs.gitea.com/installation/comparison#general-features
- **Gitea Actions**: https://docs.gitea.com/usage/actions/
- **Gitea API**: https://docs.gitea.com/api/

---

**Location**: `docs/GITEA/Gitea-Basics.md`  
**Last Updated**: 2025-01-27