---
title: "Gitea Basics Guide"
date: "2025-11-11"
captured_at: "2025-11-11"
author: ["datawarrior"]
source: { kind: doc, ref: "docs/GITEA/Gitea-Basics.md" }
source_type: personal_note
project: ["tendril"]
related_projects: ["tendril"]
topics: ["gitea", "platform", "basics", "documentation"]
tags: ["gitea", "basics", "guide", "platform", "self-hosted", "documentation"]
type: howto
status: active
phase_relevance: []
routing_hint: "Gitea platform basics guide - infrastructure/tooling documentation"
proposed_path: "kb/02_systems/"
routing_confidence: 0.95
related: ["docs/GITEA/Gitea-Basics.md"]
summary: "Comprehensive guide to Gitea platform basics including core concepts, features, differences from GitHub, terminology, and common workflows. Reference documentation for LLMs working with Gitea-based projects."
key_takeaways: []
action_candidates: []
---

# Gitea Basics Guide

## Overview

**Gitea** is a painless, self-hosted, all-in-one software development service. It includes Git hosting, code review, issue tracking, CI/CD, package registry, and 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** - Repository management, commit history, code browsing
2. **Code Review** - Pull Request workflow (same as GitHub) and AGit workflow (Gitea-specific)
3. **Issue Tracking** - Requirements, features, bugs with assignments, milestones, dependencies
4. **CI/CD** - Gitea Actions (compatible with GitHub Actions)
5. **Package Registry** - 20+ package types (Cargo, npm, PyPI, Maven, etc.)
6. **Security** - User permissions, ACLs, security-focused design

## Key Differences from GitHub

1. **Self-Hosted** - Runs on your own infrastructure
2. **Lightweight** - Fast and resource-efficient
3. **Open Source** - MIT licensed, community-driven
4. **Actions Compatibility** - Same format as GitHub Actions
5. **API Differences** - Similar but not identical to GitHub's API

## Terminology

### Same as GitHub
- Repository/Repo, Branch, Pull Request/PR, Issue, Commit, Tag, Fork, Clone

### 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 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

## For LLMs: Important Notes

- 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/`

## 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)

## 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/

---

**Original Location**: `docs/GITEA/Gitea-Basics.md`  
**Last Updated**: 2025-01-27  
**Related**: 
- `docs/GITEA/Gitea-Actions-Guide.md`
- `docs/GITEA/Gitea-Workflows.md`
- `docs/GITEA/LLM-Gitea-Guidelines.md`
- `docs/GITEA/Gitea-API-Reference.md`