Det här sätter du upp
Forgejo är en Git-server med webbgränssnitt, ungefär som GitHub: repon, ärenden, pull requests och Forgejo Actions, som kör dina tester och byggen vid varje push, med arbetsflöden som liknar GitHubs.
Här körs den under två egna användare:
forgejokör själva Forgejo, i en container, med databasen inuti. Webbgränssnittet ligger bakom Caddy från Podman-guiden, och Git ansluter över SSH på port 2222.runnerkör Forgejo Runner, som startar en ny rootless container för varje CI-jobb. Jobben kör kod från dina repon, så de får en egen användare: ett jobb kan inte röra Forgejos filer eller någon annan app på servern.
Är Git nytt för dig? Steg 9 visar hur du lägger upp kod på servern, och vad du gör när Git vägrar.
Varje steg nedan har körts på en VC-P Alloy (2 vCPU, 8 GB) hos Melonslab med Debian 13:
- Från en bärbar dator klonades ett repo över SSH, ändrades och pushades, och en befintlig mapp pushades som ett nytt repo.
- En push som Git vägrade, på grund av en ändring från en annan dator, gick igenom efter
git pull, även när båda hade ändrat samma rad. - Ett arbetsflöde hämtade koden och kördes i runnerns containrar, och en cache det sparade återställdes vid nästa körning.
- Forgejo loggade den riktiga adressen bakom en misslyckad inloggning, och CI-jobb kunde inte nå appar som bara lyssnar på serverns loopback-adress.
- Allt startade igen av sig självt efter en omstart av servern.
Forgejo använde omkring 120 MB minne, och runnern 35 MB mellan jobben.
Innan du börjar
Du behöver:
- en server uppsatt som i Podman-guiden, med Caddy igång;
- ufw påslaget som i säkerhetsguiden. Runnern öppnar portar på servern för jobbens cache, som brandväggen håller stängda mot internet;
- en A-post och en AAAA-post för
git.example.comsom pekar på din server.
Exemplen använder git.example.com, anna som ditt användarnamn och 203.0.113.10 som din servers IPv4-adress. Byt ut dem mot dina egna genomgående.
1. Öppna SSH-porten för Git
Port 22 är serverns egen SSH, så Forgejos SSH-server lyssnar på 2222. Som root:
ufw allow 2222/tcp
2. Skapa användaren
useradd -m -s /bin/bash forgejo
loginctl enable-linger forgejo
machinectl shell forgejo@
3. Skapa den hemliga nyckeln
Forgejo krypterar en del av det som lagras, till exempel hemligheterna bakom tvåfaktorsinloggningar, med en hemlig nyckel:
openssl rand -hex 32 | tr -d '\n' | podman secret create forgejo-secret-key -
4. Definiera containern
mkdir -p ~/.config/containers/systemd
Skapa ~/.config/containers/systemd/forgejo.container:
[Unit]
Description=Forgejo, a Git server
[Container]
ContainerName=forgejo
Image=codeberg.org/forgejo/forgejo:15-rootless
Volume=forgejo-data:/var/lib/gitea
# SSH for Git, open to the internet
PublishPort=2222:2222
# Web interface, reached through Caddy only
PublishPort=127.0.0.1:8089:3000
Secret=forgejo-secret-key,type=mount,target=/run/secrets/forgejo-secret-key,uid=1000,mode=0400
Environment=FORGEJO__security__SECRET_KEY__FILE=/run/secrets/forgejo-secret-key
Environment=FORGEJO__security__INSTALL_LOCK=true
Environment=FORGEJO__security__REVERSE_PROXY_TRUSTED_PROXIES=127.0.0.0/8,::1/128,203.0.113.10/32
Environment=FORGEJO__server__DOMAIN=git.example.com
Environment=FORGEJO__server__ROOT_URL=https://git.example.com/
Environment=FORGEJO__server__SSH_DOMAIN=git.example.com
Environment=FORGEJO__server__SSH_PORT=2222
Environment=FORGEJO__service__DISABLE_REGISTRATION=true
AutoUpdate=registry
[Service]
Restart=always
[Install]
WantedBy=default.target
Varje FORGEJO__-rad är en inställning i Forgejo:
INSTALL_LOCKhoppar över installationssidan, som vem som helst annars kunde använda för att ta över ett nytt Forgejo före dig.- Besökare når Forgejo via Caddy, och de anslutningarna kommer in i containern från serverns egen IPv4-adress.
REVERSE_PROXY_TRUSTED_PROXIESinnehåller den adressen, så att Forgejo loggar varje besökares riktiga adress, som Caddy skickar vidare. DISABLE_REGISTRATIONbetyder att ingen kan registrera sig själv: du skapar kontona.
Allt Forgejo lagrar, även dess SQLite-databas, finns i volymen forgejo-data. SQLite räcker gott för en person, en familj eller ett litet team. 15-rootless är Forgejos version med långtidsstöd, med buggfixar fram till juli 2027.
Starta den:
systemctl --user daemon-reload
systemctl --user start forgejo
podman logs forgejo
Loggen slutar med Starting new Web server: tcp:0.0.0.0:3000.
5. Sätt Caddy framför
Gå tillbaka till root med exit, byt till machinectl shell caddy@ och lägg till det här blocket sist i ~/Caddyfile:
git.example.com {
reverse_proxy 127.0.0.1:8089
}
Starta om Caddy med systemctl --user restart caddy.
6. Skapa ditt konto
Gå tillbaka till root med exit, sedan till machinectl shell forgejo@, och kör:
podman exec forgejo forgejo admin user create --admin --username anna --email anna@example.com --random-password
Kommandot skriver ut generated random password is '...'. Logga in på https://git.example.com med det, så ber Forgejo dig välja ett eget. Skapa konton åt andra på samma sätt, utan --admin, eller från administrationssidorna i webbgränssnittet.
7. Sätt upp runnern för Forgejo Actions
Hoppa över steg 7 och 8 om du inte behöver CI. Som root installerar du Git, som runnern behöver, och laddar ner runnern. Runnern är ett enda program, och Forgejo signerar varje version, så kontrollera signaturen innan du installerar den:
apt install -y git gpg curl
v=13.2.0
url=https://code.forgejo.org/forgejo/runner/releases/download/v$v/forgejo-runner-$v-linux-amd64
curl -fL -o forgejo-runner $url
curl -fL -o forgejo-runner.asc $url.asc
gpg --keyserver hkps://keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
gpg --verify forgejo-runner.asc forgejo-runner
Det sista kommandot måste skriva ut Good signature from "Forgejo <contact@forgejo.org>". En varning om att nyckeln inte är certifierad är normal. 13.2.0 var den senaste versionen när vi skrev det här; code.forgejo.org/forgejo/runner/releases listar nyare. Installera den och skapa användaren:
install -m 755 forgejo-runner /usr/local/bin/forgejo-runner
rm forgejo-runner forgejo-runner.asc
useradd -m -s /bin/bash runner
loginctl enable-linger runner
systemctl --user -M runner@ enable --now podman.socket
machinectl shell runner@
Runnern startar varje jobbs container via den här användarens Podman, som podman.socket ger den tillgång till.
Jobb börjar oftast med att hämta din kod från https://git.example.com, som är den här servern. Rootless-containrar delar normalt serverns egen adress och kan därför inte nå den. Skapa ~/.config/containers/containers.conf, som ger den här användarens containrar egna adresser:
mkdir -p ~/.config/containers
# Give job containers addresses of their own, so they can reach this
# server's public address, and Forgejo on it.
[network]
pasta_options = ["-a", "10.0.2.0", "-n", "24", "-g", "10.0.2.2", "--dns-forward", "10.0.2.3"]
Skapa sedan runnerns konfiguration:
forgejo-runner generate-config > ~/runner-config.yml
chmod 600 ~/runner-config.yml
Öppna ~/runner-config.yml i en editor, till exempel nano ~/runner-config.yml, och byt ut raden labels: [] mot:
labels:
- docker:docker://data.forgejo.org/oci/node:24-trixie
- ubuntu-latest:docker://data.forgejo.org/oci/node:24-trixie
Behåll de två mellanslagen i början av första raden. Ett arbetsflöde väljer runner med runs-on:, och med båda namnen körs jobbet i Debian 13 med Node.js, Git och Python.
8. Anslut runnern
Öppna https://git.example.com/admin/actions/runners i Forgejo och välj Create new runner. Ge den ett namn, till exempel server-runner, och välj Create. Forgejo visar en enda gång ett block som börjar med server: och innehåller runnerns token. Ta bort allt i ~/runner-config.yml från raden server: till slutet av filen, och klistra in blocket i stället.
Skapa ~/.config/systemd/user/forgejo-runner.service:
mkdir -p ~/.config/systemd/user
[Unit]
Description=Forgejo Runner, which runs Forgejo Actions jobs in rootless Podman
After=podman.socket
Wants=podman.socket
[Service]
ExecStart=/usr/local/bin/forgejo-runner daemon -c %h/runner-config.yml
ExecReload=/bin/kill -s HUP $MAINPID
WorkingDirectory=%h
Restart=on-failure
RestartSec=10
TimeoutStopSec=infinity
[Install]
WantedBy=default.target
Starta den:
systemctl --user daemon-reload
systemctl --user enable --now forgejo-runner
journalctl --user -u forgejo-runner
Loggen visar declared successfully, och runnersidan i Forgejo visar den som Idle.
9. Pusha din första kod
Den här delen görs på din egen dator. Git håller hela historiken för ett projekt på din dator, och git push skickar den till Forgejo.
Installera Git. På Windows installerar du Git for Windows från git-scm.com. På macOS kör du git --version i Terminal och tackar ja till att installera det. På Linux installerar du paketet git, till exempel med sudo apt install git.
Berätta för Git vem du är, en gång, i en terminal (på Windows i PowerShell eller Git Bash):
git config --global user.name "Anna Andersson"
git config --global user.email anna@example.com
git config --global init.defaultBranch main
git config --global pull.rebase true
Ditt namn och din e-postadress hamnar på varje ändring du sparar. Den tredje raden ger din första gren namnet main, som Forgejo gör. Den sista förklaras under "När Git vägrar" nedan.
Lägg till din SSH-nyckel i Forgejo. Använd nyckeln från steg 1 i säkerhetsguiden, eller skapa en med ssh-keygen -t ed25519. Visa den publika nyckeln:
cat ~/.ssh/id_ed25519.pub
Öppna menyn under din avatar uppe till höger i Forgejo, välj Settings, sedan SSH / GPG keys och Add key. Klistra in hela raden, som börjar med ssh-ed25519, och välj Add key.
Skapa ett repo. Välj + uppe till höger och sedan New repository. Döp det till hello, kryssa i Initialize repository och välj Create repository.
Kopiera det till din dator:
git clone ssh://git@git.example.com:2222/anna/hello.git
cd hello
Repots sida visar samma adress när du väljer SSH. Första gången frågar SSH om du litar på servern: skriv yes.
Ändra något och skicka det. Öppna README.md i valfri editor, lägg till en rad och spara. Sedan:
git add README.md
git commit -m "Say hello"
git push
git add väljer ändringarna som ska sparas, git commit sparar dem som ett steg i historiken, på din dator, och git push skickar dina nya steg till Forgejo. Ladda om repots sida för att se ändringen. git status visar vad du har ändrat och inte sparat än.
Lägg upp en befintlig mapp på Forgejo. Skapa ett repo som ovan, men lämna rutan Initialize repository omarkerad, så att repot blir tomt. I mappen:
git init
git add .
git commit -m "First commit"
git remote add origin ssh://git@git.example.com:2222/anna/myproject.git
git push -u origin main
Efter den första pushen räcker git push. För att hämta ändringar som gjorts någon annanstans, till exempel på en annan dator, kör du git pull.
När Git vägrar
! [rejected] main -> main (fetch first). Forgejo har ändringar som du inte har än, till exempel från din andra dator. Kör git pull och sedan git push igen. Med pull.rebase inställt som ovan lägger git pull dina nya steg efter dem från Forgejo.
CONFLICT efter git pull. Din ändring och den andra ändringen rör samma rader. Git markerar dem i filen, mellan <<<<<<< och >>>>>>>. Redigera filen så att det du vill ha blir kvar och ta bort markeringsraderna, och kör sedan git add med filens namn och git rebase --continue. Om Git öppnar en editor med stegets meddelande, spara och stäng den. Kör sedan git push. git rebase --abort ångrar i stället hela git pull.
error: src refspec main does not match any. Det finns inget att pusha än. Kör git add och git commit först.
Permission denied (publickey). Forgejo godtog inte din nyckel. Kontrollera att den är tillagd under SSH / GPG keys, och att adressen börjar med ssh://git@: alla konton använder git, och Forgejo skiljer dem åt på nyckeln.
10. Kör ett arbetsflöde
Skapa .forgejo/workflows/test.yml i ett repo:
on: [push]
jobs:
test:
runs-on: docker
steps:
- uses: actions/checkout@v5
- run: ls
Lägg till, spara och pusha det. Repots flik Actions visar körningen och utdata från varje steg. Många arbetsflöden som skrivits för GitHub fungerar utan ändringar, med runs-on: ubuntu-latest. Även de jobben körs på den här runnern, i samma Debian-avbild, som har mindre programvara installerad än GitHubs egna maskiner.
11. Håll den uppdaterad
Slå på Podmans dagliga uppdateringar som forgejo:
systemctl --user enable --now podman-auto-update.timer
Med taggen 15-rootless får du alla buggfixar inom Forgejo 15. Till nästa version med långtidsstöd byter du själv genom att ändra taggen, efter att ha läst Forgejos versionsanteckningar. För en ny runnerversion upprepar du nedladdningen i steg 7 med dess nummer och kör sedan systemctl --user restart forgejo-runner som runner. Runnern laddar ner jobbavbilden en gång och behåller den sedan; kör podman pull data.forgejo.org/oci/node:24-trixie som runner för att hämta den senaste.
12. Säkerhetskopiera
Som forgejo:
mkdir -p ~/backup
systemctl --user stop forgejo
podman volume export forgejo-data --output ~/backup/forgejo-data.tar
systemctl --user start forgejo
Säkerhetskopian innehåller varje repo, databasen och Forgejos inställningar. Kopiera sedan ~/backup till en annan maskin och förvara den säkert.
Felsökning
Git kan inte ansluta på port 2222. Kontrollera ufw-regeln från steg 1, och att systemctl --user status forgejo visar att Forgejo körs, som forgejo.
Ett jobb väntar och startar aldrig. Ingen runner har namnet på jobbets runs-on:-rad. Kontrollera att det är docker eller ubuntu-latest, och att runnern visas som Idle på /admin/actions/runners.
Hämtningssteget misslyckas med Failed to connect to git.example.com port 443. Jobbets container delar serverns adress. Kontrollera ~/.config/containers/containers.conf från steg 7, som runner.