Gitea

What it's good for#

If you write code, keep configuration in Git, or just want your projects somewhere that isn't a company's servers, Gitea gives you the familiar set: repositories you browse in the browser, issues to track what needs doing, pull requests to review changes, a wiki per project, and releases with downloadable files. It also has a package registry, so you can keep your own container images next to the code that builds them.

It's small enough to run happily on a modest box, and it suits one person with a pile of side projects just as well as a small team.

Signing in#

There's no sign-up page and no setup wizard to grab. LibrePortal locks Gitea's installer and, once Gitea is answering, makes the admin account with Gitea's own command-line tool. The account is libreportal-admin, and its password is in the Login Details shown when the install finishes; press Welcome on the app's page to see it again.

The admin gets a made-up address, gitea-admin@ followed by Gitea's host name (or gitea-admin@gitea.invalid if Gitea is on a plain IP address), which Gitea keeps hidden. That's deliberate. Gitea credits every commit to the account whose email matches the commit's author, so if the admin had the address you commit with, all your work would show up as the admin's. Give yourself a normal account for everyday work (see below) and keep the admin for running the server.

Change the admin's password with the Reset User Password tool rather than inside Gitea. It changes it in both places, so the password LibrePortal shows you stays right.

First steps#

New repositories start private. Make one public in its settings when you want other people to see it.

The other tools do what they say: List Users, List Repositories (with whether each is public or private), Set Admin Status (it won't demote the last admin, so you can't lock yourself out) and Delete User Account, which can't be undone.

Pushing and pulling#

Every repository shows two clone addresses. The HTTP one uses the web address. The SSH one uses Gitea's second port, Git SSH Access, which LibrePortal picked at install, so it looks like ssh://git@192.168.1.50:<port>/you/project.git. The port is already in the address Gitea shows you, so copy it rather than typing it.

The SSH port only answers your trusted places: your home network, your own addresses and your VPN devices. Pushing from elsewhere works over the LibrePortal VPN.

Who can see what#

Gitea's web page is public from the start, because the point of public repositories is that anyone can read them. What makes that safe depends on whether you have a domain.

With a domain and Traefik, Gitea lives at git.<your domain> over HTTPS, and LibrePortal splits it in two. Browsing and cloning public repositories works for anyone. Signing in, account recovery, your settings, the site admin, anything that changes data through the API, and any request carrying a password or token only answer your trusted places. Someone outside can read your public code, but can't even try a password. Anonymous docker pull of public packages works from anywhere too; logging in to the registry and pushing images don't.

Without Traefik, Gitea is plain http://192.168.1.50:<port> with no such split, sign-in page included, so anyone who can reach your server can reach it. If your server is reachable from the internet, set the port to private until you've got a domain set up.

If you'd rather nobody outside saw anything, set the Web Interface port to private and it's yours alone.

Works with#

With Prometheus and Grafana installed, switch on Export metrics to Grafana on Gitea's Config tab. Prometheus starts collecting Gitea's figures and Grafana gets a Gitea dashboard: memory and CPU, plus counts of repositories, users, issues, stars and the rest. The figures sit behind a token LibrePortal generates, since they'd otherwise ride on the public web port.

Uptime Kuma watches it like any other app.

Good to know#

• Updates wait for you. Gitea changes its database the first time a new version starts, and there's no going back. So LibrePortal starts it on Manual and pins it to an exact release: pressing Update brings fresh builds of that release, and it never jumps to a new version on its own at six in the morning. When the Updates tab shows a newer version, Upgrade moves Gitea up one version at a time, taking a backup and checking it works at each step, so you do it when you've read the release notes. A backup is taken before any update. See Updates.
• Its address is fixed at install. Clone links and page links use the address Gitea was set up with: git.<your domain>, or your server's network address and port. If you add a domain later, or the server's address changes, run Update Configuration so Gitea picks up the new one. If the domain's DNS record didn't point at your server yet, no HTTPS certificate was requested; add the record and do the same.
• It runs a small cache beside it, Redis, which keeps pages quick. It's part of the app, and backed up and updated with it.
• No email. Gitea has no mail server to use, so there are no notification emails or password-reset links. Use Reset User Password.
• It doesn't call out. Avatars and page assets come from Gitea itself, not from Gravatar or other outside sites.
• No CI runner. Gitea Actions needs a separate runner program, which LibrePortal doesn't install.
• Backups include everything: the database, the repositories, uploads and packages.
• You can run more than one. Gitea can run as several copies, each with its own data and address.