ThetaDev
1dc8c5cef4
All checks were successful
ci/woodpecker/push/woodpecker Pipeline was successful
327 lines
15 KiB
Markdown
327 lines
15 KiB
Markdown
# Gitea
|
|
|
|
Das Gitea-Projekt begann 2016 als Fork der Git-Hosting-Plattform Gogs. Lunny Xiao, einer
|
|
der Beitragenden von Gogs, war damit unzufrieden, dass der Gründer des Projekts, Joe
|
|
Chen, das Projekt alleine betreuen und keine weiteren Maintainer ernennen wollte.
|
|
|
|
2022 gründete Lunny Xiao die Firma Gitea Limited. Die Firma bietet Unternehmen Hosting-
|
|
und Supportdienstleistungen für Gitea an. Da einige Mitglieder der Community einem
|
|
kommerziell geleiteten Open-Source-Projekt misstrauen, entstand ein neuer Fork names
|
|
Forgejo. Forgejo steht unter der Leitung von Codeberg, einem Berliner Verein, der seit
|
|
2018 eine öffentliche Gitea-Instanz betreibt. Abgesehen von Design- und Namensänderungen
|
|
unterscheidet sich Forgejo von Gitea momentan kaum.
|
|
|
|
Gitea ist in Go geschrieben und besteht aus einer einzigen ausführbaren Datei.
|
|
Standardmäßig verwendet Gitea eine interne SQLite-Datenbank, alternativ werden auch
|
|
externe Datenbanken (MySQL, MariaDB, Postgres, MS SQL) unterstützt.
|
|
|
|
Die Weboberfläche wied serverseitig mit Templates gerendert. Einige Websitekomponenten
|
|
wie z.B. Drop-Down-Menüs erfordern JavaScript.
|
|
|
|
Getestet wurde die Version 1.20.0-rc2.
|
|
|
|
## Installation
|
|
|
|
Gitea stellt kompilierte Binaries für alle gängigen Betriebssysteme unter
|
|
<https://dl.gitea.com/gitea/> zur Verfügung. Von dort aus lässt sich die Anwendung
|
|
einfach herunterladen und starten.
|
|
|
|
Alternativ gibt es auch [offizielle](https://pkgs.org/download/gitea) und
|
|
[inoffizielle](https://gitea.com/gitea/awesome-gitea/src/branch/main/README.md#user-content-packages)
|
|
Pakete für die meisten Linux-Distributionen.
|
|
|
|
Darüber hinaus stellt Gitea auch ein Docker-Image (`gitea/gitea`) zur Verfügung.
|
|
|
|
Die Einrichtung ist extrem simpel. Beim ersten Start wird diese Konfigurationsseite
|
|
angezeigt, auf der man die grundlegenden Einstellungen (z.B. Datenbank-URL,
|
|
Admin-Passwort) vornehmen kann. Nach der Bestätigung ist Gitea in wenigen Sekunden
|
|
bereit zur Verwendung.
|
|
|
|
|
|
|
|
Dieser Konfigurationsassistent wird jedoch nur beim ersten Start angezeigt. Alle
|
|
weiteren Konfigurationsänderungen müssen durch die
|
|
`app.ini`-[Konfigurationsdatei](https://docs.gitea.com/1.20/administration/config-cheat-sheet)
|
|
erfolgen. Gitea verfügt zwar über eine Admin-Oberfläche, diese dient allerdings
|
|
hauptsächlich der Nutzerverwaltung und erlaubt keine Konfigurationsänderungen.
|
|
|
|
## Systemanforderungen
|
|
|
|
Gitea ist auf jedem Betriebssystem und jeder CPU-Architektur lauffähig, die von der
|
|
Programmiersprache Go unterstützt wird. Binaries für MacOS (amd64/aarch64), FreeBSD
|
|
(amd64), Windows (i386/amd64) und Linux (i386/amd64/arm5/arm6/aarch64) werden offiziell
|
|
zum Download angeboten. Das offizielle Docker-Image ist für die amd64- und
|
|
aarch64-Architektur verfügbar.
|
|
|
|
Im Leerlauf benötigt der Server ca. 150MB Arbeitsspeicher und verursacht unter 0.1%
|
|
CPU-Auslastung. Damit ist Gitea die mit Abstand leichtgewichtigste Plattform in Test und
|
|
eignet sich perfekt für den Einsatz auf schwächerer Hardware.
|
|
|
|
## Bedienung
|
|
|
|
Die Weboberfläche von Gitea wird serverseitig mit Hilfe von Templates gerendert
|
|
(klassische Multi-Page-Anwendung). Dies hat den Vorteil, dass die Seite auch ohne
|
|
JavaScript dargestellt werden kann (wenn auch mit eingeschränkter Bedienbarkeit).
|
|
|
|
Obwohl bei jedem Navigationsschritt durch ein Repository die gesamte Seite neu geladen
|
|
wird, läuft die Navigation durch Ordner sehr flüssig.
|
|
|
|
Optisch und funktional ist die Benutzerschnittstelle stark an GitHub angelehnt. Wer also
|
|
vorher GitHub verwendet hat, findet sich auf Gitea schnell zurecht
|
|
|
|
Der Code in Gitea-Repositories kann durchsucht werden, allerdings ist diese Funktion
|
|
standardmäßig deaktiviert. Um sie zu aktivieren, müssen diese Zeilen zur
|
|
Konfigurationsdatei hinzugefügt werden:
|
|
|
|
```
|
|
[indexer]
|
|
REPO_INDEXER_ENABLED=true
|
|
```
|
|
|
|
Standardmäßig verwendet Gitea die Bibliothek [Bleve](https://blevesearch.com/) für die
|
|
Suche, es kann jedoch auch eine externe Elasticsearch-Instanz verwendet werden.
|
|
|
|
|
|
|
|
Gitea kann standardmäßig Bilder, CSV-Dateien, PDFs und Markdown-Dateien auf der
|
|
Weboberfläche darstellen. Andere Markupsprachen wie ReStructured Text werden
|
|
standardmäßig nicht unterstützt. Allerdings bietet Gitea als einzige getestete Plattform
|
|
die Möglichkeit, zusätzliche Renderer in der Konfigurationsdatei zu definieren.
|
|
Beispielsweise kann Gitea Pandoc verwenden, um RST, LaTEX oder Word-Dokumente in HTML zu
|
|
konvertieren und anzuzigen. Es ist auch möglich, mit etwas Bastelei einen Viewer für STL
|
|
oder Excel-Dateien zu installieren.
|
|
|
|
## Import bestehender Projekte
|
|
|
|
Gitea bietet die Möglichkeit, Projekte von GitHub, Gitlab, Gogs, OneDev, GitBucket und
|
|
Codebase zu importieren. Neben den Repositories können auch Issues, Pull-Requests und
|
|
Releases importiert werden.
|
|
|
|
Der Versuch, zwei meiner GitHub-Projekte mit Issues und Pull-Requests zu übertragen,
|
|
scheiterte jedoch mit einer Fehlermeldung.
|
|
|
|
## Zusatzfeatures
|
|
|
|
Gitea bietet grundlegende Features zum Projektmanagement. Issues können erstellt, mit
|
|
Labels versehen und bestimmten Entwicklern zugewiesen werden. Es können
|
|
Fälligkeitstermine für Issues festgelegt und die Arbeitszeit hinterlegt werden.
|
|
|
|
Dazu kommt die Möglichkeit, Issues zu Meilensteinen hinzuzufügen und somit
|
|
beispielsweise den Arbeitsfortschritt für eine neue Version zu verfolgen.
|
|
|
|
Darüber hinaus können in Gitea Kanbanboards erstellt werden. Allerdings sind diese
|
|
Boards nicht in das restliche Issue-System integriert und deswegen umständlich zu
|
|
nutzen. Issues müssen beispielsweise manuell den Boards hinzugefügt werden. Während
|
|
GitLab Labels verwendet, um die Issues den Spalten zuzuordnen ist in Gitea außerhalb des
|
|
Boards nicht ersichtlich, welchen Status ein Issue hat. Ein Issue, das in die
|
|
Done-Spalte verschoben wird, wird nicht automatisch geschlossen. Umgekehrt führt das
|
|
Schließen eines Issues nicht zu einer Platzierung in der Done-Spalte.
|
|
|
|
Dokumentation für Gitea-Repositories kann in einem simplen, auf Markdown basierenden
|
|
Wiki veröffentlicht werden.
|
|
|
|
Das Hosting statischer Webseiten unterstützt Gitea nicht, weswegen das Team von Codeberg
|
|
hierfür eine [eigene Lösung](https://codeberg.org/Codeberg/pages-server) entwickelt hat.
|
|
|
|
Gitea bietet eine integrierte Registry für Pakete aller gängigen Programiersprachen
|
|
(z.B. Python, npm, Rust). Wer eine Softwarebibliothek entwickelt, kann diese auf seiner
|
|
Gitea-Instanz veröffentlichen, sodass andere Entwickler sie nutzen können. Zudem
|
|
unterstützt die Gitea-Registry Linux-Pakete (.deb und .rpm) sowie Docker-Images.
|
|
|
|
Gitea unterstützt als einzige getestete Plattform agit. Dies ist ein alternativer
|
|
Git-Workflow, der von Alibaba entwickelt wurde. Agit erlaubt es Entwicklern, Pull
|
|
Requests zu erstellen ohne zuvor einen Fork des Projekts anzulegen. Hierbei wird die
|
|
Änderung mit diesem Befehl in einen versteckten Branch des Reposiories gepusht, worauf
|
|
Gitea automatisch eine PR erstellt.
|
|
|
|
Dieser Befehl erfordert im Gegensatz zum normalen push keine Schreibrechte im
|
|
entsprechenden Repository.
|
|
|
|
```
|
|
git push origin HEAD:refs/for/main -o topic="feat/user-search" -o title="Add user search"
|
|
```
|
|
|
|
Es existiert auch ein Git-Plugin für agit namens
|
|
[`git-repo`](https://git-repo.info/en/2020/03/agit-flow-and-git-repo/), damit man nicht
|
|
jedes Mal diesen langen Befehl eintippen muss, sondern den Beschreibungstext direkt in
|
|
die Kommandozeile tippen kann.
|
|
|
|
Gitea lässt sich auch mit dem Tool [`tea`](https://gitea.com/gitea/tea) auf der
|
|
Kommandozeile bedienen. Auf diese Weise lassen sich Issues erstellen und lesen oder Pull
|
|
Requests erstellen und abrufen.
|
|
|
|
Gitea bietet dem Administrator vollen Zugriff auf seinen Webserver und das
|
|
Templatesystem. Dadurch kann man Templates und Stylesheets durch eigens angepasste
|
|
Versionen ersetzen und die Weboberfläche nach seinen Bedürfnissen anpassen. Dies ist
|
|
insbesondere für große Organisationen und Firmen interessant, die ihre
|
|
Git-Hosting-Plattform nach ihrem Corporate Design gestalten möchten.
|
|
|
|
Ein Beispiel für eine stark angepasste Gitea-Oberfläche ist die Instanz des
|
|
[Blender-Projekts](https://projects.blender.org/), die sich nahtlos in die restliche
|
|
Projektseite einfügt.
|
|
|
|
## Continous Integration
|
|
|
|
### Woodpecker
|
|
|
|
Gitea verfügte lange nicht über einen eingebauten CI-Server. Allerdings gibt es eine
|
|
Schnittstelle, um externe CI-Systeme anzubinden.
|
|
|
|
Ich habe einige CI-Systeme getestet, die mit Gitea kompatibel sind.
|
|
[Woodpecker](https://woodpecker-ci.org/) ist meiner Meinung nach eines der besten
|
|
Systeme. Bei Woodpecker handelt es sich um einen Fork des Drone CI-Projekts nach deren
|
|
Wechsel von der Apache License zu einer nichtkommerziellen Lizent.
|
|
|
|
Woodpecker erlaubt den Login mit seinem Gitea-Account und zeigt dem Entwickler auf der
|
|
Startseite eine Liste aller Repositories an. Von dort aus lässt sich die CI für
|
|
bestimmte Repositories aktivieren. Daraufhin konfiguriert Woodpecker die Webhooks des
|
|
Repositories, sodass die Builds automatisch bei Aktualisierungen gestartet werden.
|
|
|
|
Woodpecker verwendet sogenannte Agents, die mittels GRPC mit dem zentralen Server
|
|
kommunizieren und Buildaufträge empfangen. Die Agents verwenden Docker, um die Builds in
|
|
Containern auszuführen.
|
|
|
|
|
|
|
|
Die Builds werden in einer yml-Datei mit dem Namen `.woodpecker.yml` im
|
|
Wurzelverzeichnes des Repositories definiert. Jeder Buildschritt wird in einem eigenen
|
|
Docker-Container ausgeführt.
|
|
|
|
```yaml
|
|
pipeline:
|
|
test:
|
|
image: rust:latest
|
|
commands:
|
|
- rustup component add rustfmt clippy
|
|
- cargo fmt --all --check
|
|
- cargo clippy --all --features=rss -- -D warnings
|
|
- cargo test --features=rss --workspace
|
|
```
|
|
|
|
Die Installation von Woodpecker ist etwas komplizierter, da Woodpecker sowohl einen
|
|
HTTP-Server als auch einen GRPC-Server bereitstellt. Möchte man Agents auf anderen
|
|
Servern betreiben, sollte auch der GRPC-Server mit TLS gesichert sein. Hierfür kann man
|
|
einen Reverse Proxy (z.B Traefik) verwenden. Allerdings beinhaltet die offizielle
|
|
Dokumentation keine Anleitung hierfür.
|
|
|
|
[Hier](./assets/woodpecker/docker-compose.yml) ist die Docker-Compose-Datei, die ich für
|
|
meine Setup (mit Traefik) verwendet habe. Vor der Verwendung müssen noch die folgenden
|
|
Konfigurationsvariablen bearbeitet werden:
|
|
|
|
- `WOODPECKER_HOST` URL der Woodpecker-Instanz
|
|
- `WOODPECKER_GITEA_URL` URL der Gitea-Instanz
|
|
- `WOODPECKER_GITEA_CLIENT` / `WOODPECKER_GITEA_SECRET` OAuth-Zugangsdaten (in Gitea das
|
|
Einstellungsmenü aufrufen und unter _Create a new OAuth2 Application_ einen neuen
|
|
Client erstellen. Redirect URI: `<WOODPECKER_URL>/authorize`)
|
|
- `WOODPECKER_AGENT_SECRET` ist das Passwort für alle mit der Instanz verbundenen
|
|
Agents. Hierfür sollte man sich einfach einen langen Zufallsstring erzeugen,
|
|
beispielsweise mit `openssl rand -hex 32`.
|
|
|
|
### Gitea Actions
|
|
|
|
Mit dem vorletzten Release 1.19 bekam Gitea jedoch ein eigenes CI-System: Gitea Actions.
|
|
Hierbei wurde nicht nur der Name an die Konkurrenz von Microsoft angelehnt. Das System
|
|
basiert auf [act](https://github.com/nektos/act), einer freien Implementation von GitHub
|
|
Actions. Ursprünglich wurde act zum lokalen Testen von GitHub Actions entwickelt. Gitea
|
|
hat die Anwendung stattdessen als Basis für ihr CI-System verwendet.
|
|
|
|
Standardmäßig sind Gitea Actions in den Einstellungen deaktiviert. Um sie verwenden zu
|
|
können, muss man diese Zeilen zur Konfigurationsdatei hinzufügen:
|
|
|
|
```
|
|
[actions]
|
|
ENABLED=true
|
|
```
|
|
|
|
Anschließend muss man wie bei Gitlab und Woodpecker einen Runner einrichten, der die
|
|
Builds mittels Docker ausführt. Der Runner kann als Binary von der
|
|
[Gitea-Download-Seite](https://dl.gitea.com/act_runner/) heruntergeladen werden. Es ist
|
|
auch möglich, den Runner in einem Docker-Container zu betreiben.
|
|
|
|
Nachdem man den Runner heruntergeladen hat, muss man ihn konfigurieren. Dafür führt man
|
|
den Befehl `act-runner register` auf. Anschließend muss man die Adresse der Instanz und
|
|
einen Registrierungstoken, den man in der Admin-Oberfläche unter _Actions / Runners_
|
|
erzeugen kann.
|
|
|
|
Anschließend muss man noch die Actions im gewünschten Repository aktivieren, in dem man
|
|
in den Einstellungen den Haken bei _Enable Repository Actions_ setzt.
|
|
|
|
Die Builds werden als yaml-Dateien im Verzeichnis `.gitea/workflows` definiert. Obwohl
|
|
Gitea die gleiche Syntax wie Github Actions verwendet, sind die Workflows nicht 1:1
|
|
kompatibel. Beispielsweise lädt Gitea vordefinierte Actions wie `actions/checkout` nicht
|
|
von [github.com/actions](https://github.com/actions) sondern von
|
|
[gitea.com/actions](https://gitea.com/actions) herunter, sodass einige Actions nicht
|
|
verfügbar sind.
|
|
|
|
Außerdem führt GitHub seine Builds in einer virtuellen Maschine mit einer Vielzahl an
|
|
vorinstallierten Programmiersprachen und Entwicklertools aus. Da das Image dieser
|
|
Maschine sehr groß ist, benutzt Gitea stattdessen standardmäßig den
|
|
Debian+NodeJS-Container `node:16-bullseye`. Das Image enthält neben Node.js auch Python,
|
|
gcc, make und curl. Wer andere Programmiersprachen benutzt, muss jedoch Anwendungen
|
|
nachinstallieren (wie beispielsweise Rust im unteren Beispiel). Es ist jedoch möglich,
|
|
andere Docker-Images zu verwenden.
|
|
|
|
```yaml
|
|
name: Test
|
|
on: [push]
|
|
|
|
jobs:
|
|
Test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Check out repository code
|
|
uses: actions/checkout@v3
|
|
- name: Setup Rust
|
|
run: |
|
|
curl https://sh.rustup.rs -sSf | sh -s -- -y
|
|
source "$HOME/.cargo/env"
|
|
- name: Test
|
|
run: |
|
|
cargo clippy
|
|
cargo test
|
|
```
|
|
|
|
|
|
|
|
Ein wichtiges Feature, das Gitea Actions momentan noch fehlt ist die Möglichkeit,
|
|
Workflows manuell zu starten. Da Gitea Actions noch relativ neu ist, gehe ich jedoch
|
|
davon aus, dass dieses Feature in Zukunft implementiert wird.
|
|
|
|
## Öffentliche Instanzen
|
|
|
|
Die von den Maintainern des Projekts betriebene Instanz unter
|
|
[gitea.com](https://gitea.com/explore/repos) verfügt über 5600 Repositories.
|
|
|
|
Eine noch größere Instanz betreibt der Berliner Verein Codeberg e.V. Auf
|
|
[codeberg.org](https://codeberg.org) werden 30900 öffentliche Repositories gehostet.
|
|
Zusätzlich zu ihrer Gitea-Instanz bietet Codeberg auch einen Webhosting-Dienst unter
|
|
[\*.codeberg.page](codeberg.page) an. Codeberg betreibt auch einen Woodpecker-CI-Server,
|
|
für dessen Verwendung die Nutzer allerdings manuell freigeschaltet werden müssen.
|
|
|
|
Da Gitea sehr einfach und günstig zu hosten ist, wird es von einigen Open
|
|
Source-Projekten auch als sekundäre Plattform zusätzlich zu GitHub verwendet.
|
|
Beispielsweise betreibt das Team hinter dem alternativen YouTube-Frontend Invidious eine
|
|
[Gitea-Instanz](https://gitea.invidious.io/iv-org), um vor eventuellen Takedowns des
|
|
Repositories auf GitHub sicher zu sein
|
|
|
|
## Fazit
|
|
|
|
Während GitLab meiner Meinung nach die beste Lösung für große Organisationen und
|
|
Unternehmen darstellt, ist Gitea das perfekte System für einzelne Entwickler, kleine
|
|
Teams und Hobbybastler. Durch seinen sparsamen Ressourcenverbrauch ist Gitea auf fast
|
|
jeder Hardware lauffähig und die Einrichtung funktioniert einfach und schnell.
|
|
|
|
Darüber hinaus lässt sich Gitea mit eigenen Themes und Templates individuell anpassen
|
|
und zu seiner persönlichen Website machen.
|
|
|
|
Die Projektmanagement-Features von Gitea sind allerdings eher rudimentär. Wer
|
|
Kanbanboards benötigt, sollte Gitlab oder OneDev in Betracht ziehen oder hierfür eine
|
|
externe Software verwenden.
|
|
|
|
## Quellen
|
|
|
|
- Projektseite <https://gitea.com>
|
|
- Repository <https://github.com/go-gitea/gitea/>
|
|
- Start von Codeberg (damals TeaHub)
|
|
<https://www.heise.de/news/Neue-Entwickler-Plattform-TeaHub-will-Github-beerben-4078811.html>,
|
|
<https://blog.codeberg.org/codebergorg-launched.html>
|