first version of the knowledge base :)

70 - Tools/gitea/gitea.md

@@ -0,0 +1,63 @@
+---
+title: Gitea
+description: Tool overview for Gitea as a lightweight self-hosted Git forge
+tags:
+  - gitea
+  - git
+  - self-hosting
+category: tools
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Gitea
+
+## Summary
+
+Gitea is a lightweight self-hosted Git forge that provides repositories, issues, pull requests, user and organization management, and optional automation features. It is commonly used as a self-hosted alternative to centralized Git hosting platforms.
+
+## Why it matters
+
+For self-hosted environments, Gitea offers source control and collaboration without the operational weight of larger enterprise platforms. It is often a good fit for homelabs, small teams, and private infrastructure repositories.
+
+## Core concepts
+
+- Repositories, organizations, and teams
+- Authentication and user management
+- Webhooks and integrations
+- Actions or CI integrations depending on deployment model
+- Persistent storage for repository data and attachments
+
+## Practical usage
+
+Gitea commonly fits into infrastructure as:
+
+```text
+Users and automation -> Gitea -> Git repositories -> CI or deployment systems
+```
+
+Typical uses:
+
+- Hosting application and infrastructure repositories
+- Managing issues and pull requests in a private environment
+- Acting as a central source of truth for docs-as-code workflows
+
+## Best practices
+
+- Back up repository data, configuration, and the database together
+- Integrate with centralized identity when possible
+- Put Gitea behind a reverse proxy with a stable external URL
+- Protect administrator access with MFA or a private access layer
+
+## Pitfalls
+
+- Treating Git repository data as sufficient without backing up the database and config
+- Allowing base URL and reverse proxy headers to drift out of sync
+- Running a forge without monitoring, backup validation, or update planning
+- Using one shared administrator account for normal operations
+
+## References
+
+- [Gitea Documentation](https://docs.gitea.com/)
+- [Gitea administration docs](https://docs.gitea.com/administration)
+- [Gitea installation docs](https://docs.gitea.com/installation)