Ten artykuł dostępny jest również w języku angielskim (English).
SourceHut (git.sr.ht) — Podręcznik administracyjny
version 1.0, 2026-08-10
- 1. Cel
- 2. Wprowadzenie
- 3. Wymagania
- 4. Krótkie omówienie technologii
- 5. Diagram architektury
- 6. Instrukcja krok po kroku
- 6.1. 1. Utworzenie konta na SourceHut
- 6.2. 2. Wygenerowanie klucza SSH Ed25519
- 6.3. 3. Dodanie klucza publicznego do konta SourceHut
- 6.4. 4. Konfiguracja ~/.ssh/config
- 6.5. 5. Test połączenia SSH
- 6.6. 6. Utworzenie repozytorium na SourceHut
- 6.7. 7. Konfiguracja zdalnego repozytorium
- 6.8. 8. Pierwszy push
- 6.9. 9. Klonowanie repozytorium
- 6.10. 10. Zarządzanie wieloma repozytoriami
- 6.11. 11. Konfiguracja domyślnej gałęzi i aliasów Git
- 6.12. 12. Podpisywanie commitów (SSH)
- 7. Omówienie wszystkich poleceń
- 8. Weryfikacja poprawności
- 9. Diagnostyka
- 10. Typowe błędy
- 11. Dobre praktyki
- 12. Bezpieczeństwo
- 13. Podsumowanie
- 14. Checklista
- 15. Najczęstsze problemy
- 16. Dalsza lektura
- 17. Najlepsze praktyki produkcyjne
1. Cel
Celem niniejszego dokumentu jest przeprowadzenie administratora systemu (lub inżyniera DevOps) przez cały cykl pracy z SourceHut — od założenia konta, przez konfigurację kluczy SSH Ed25519, aż po zarządzanie wieloma repozytoriami Git. Każdy krok jest szczegółowo opisany, opatrzony przykładem, wyjaśnieniem działania, typowymi błędami i sposobem ich naprawy.
2. Wprowadzenie
SourceHut (https://git.sr.ht) to minimalistyczna, open-source’owa platforma do hostowania projektów, rozwijana przez Drew DeVaulta. W odróżnieniu od GitHuba czy GitLaba, SourceHut kładzie nacisk na:
-
prostotę i szybkość,
-
pracę w terminalu (brak zbędnego GUI),
-
użycie SSH jako jedynego protokołu uwierzytelniania (Git),
-
wsparcie dla poczty elektronicznej jako głównego kanału współpracy (patch series),
-
brak JavaScriptu w interfejsie WWW.
SourceHut nie wspiera uwierzytelniania HTTP(S) dla operacji Git — każda interakcja wymaga pary kluczy SSH. To wymuszenie nie jest przypadkowe: eliminuje całą klasę ataków związanych z hasłami i tokenami dostępu.
3. Wymagania
Zanim rozpoczniesz, upewnij się, że spełniasz następujące warunki:
-
Gentoo Linux z działającym Portage (lub inna dystrybucja, aczkolwiek przykłady opierają się na Gentoo).
-
Zainstalowany OpenSSH (zgłasza
ssh -Vwersję >= 9.x). -
Zainstalowany Git (zgłasza
git --versionwersję >= 2.40). -
Działające połączenie z Internetem (port 22/TCP do
git.sr.ht). -
Konto pocztowe (wymagane do rejestracji na SourceHut).
-
Przeglądarka internetowa (jednorazowo do rejestracji i dodania klucza).
3.1. Weryfikacja wstępna
$ ssh -V
OpenSSH_9.7_p1, OpenSSL 3.0.15 3 Sep 2024
$ git --version
git version 2.47.0
$ echo $SHELL
/bin/bash
Jeśli któregoś z narzędzi brakuje, zainstaluj je:
# emerge --ask dev-vcs/git net-misc/openssh
4. Krótkie omówienie technologii
4.1. SSH (Secure Shell)
SSH to protokół tunelowania, uwierzytelniania i przesyłania danych. SourceHut używa go w dwóch rolach:
-
Uwierzytelnienie przy push/fetch do repozytorium Git.
-
Transport danych Git (protokół
git-upload-pack/git-receive-packprzez kanał SSH).
4.2. Ed25519
Ed25519 to algorytm podpisu krzywej eliptycznej zaprojektowany przez Daniela J. Bernsteina. Jest domyślnym wyborem w podręczniku, ponieważ:
-
klucze mają zaledwie 256 bitów (nawet krótsze niż RSA 4096),
-
operacje podpisu są błyskawiczne,
-
implementacja jest odporna na timing attacki,
-
OpenSSH domyślnie priorytetyzuje Ed25519 od wersji 8.9.
4.3. Git over SSH
Git nie posiada własnego protokołu uwierzytelniania — deleguje je do
warstwy transportowej. W przypadku SSH oznacza to, że cała autoryzacja
odbywa się po stronie serwera na podstawie klucza publicznego zapisanego
w ~/.ssh/authorized_keys użytkownika na serwerze. SourceHut przechowuje
klucze publiczne na swoim backendzie i mapuje je na konta użytkowników.
5. Diagram architektury
+----------------------------------------------------+
| Stacja robocza |
| +----------------------------------------------+ |
| | ~/.ssh/ | |
| | id_ed25519 (klucz prywatny) | |
| | id_ed25519.pub (klucz publiczny) | |
| | config (konfiguracja SSH) | |
| | known_hosts (fingerprinty serwerów)| |
| +----------------------------------------------+ |
| | ~/src/ | |
| | moj-projekt/ | |
| | .git/ | |
| | src/ | |
| +----------------------------------------------+ |
+----------------------------------------------------+
| |
| TCP/22 --- SSH auth via Ed25519 |
| Git protocol tunelowany w SSH |
v v
+---------------------------+ +-----------------------------+
| git.sr.ht:22 | | man.sr.ht |
| ~/.ssh/authorized_keys | | (lista kluczy publicznych) |
| (automatycznie | | |
| zarządzane przez | | Rejestracja, |
| SourceHut backend) | | dodawanie/usuwanie kluczy |
| | | przez WWW |
+---------------------------+ +-----------------------------+
|
v
+-------------------------------+
| Repozytorium na serwerze |
| /srv/git/~twojanazwa/ |
| moj-projekt.git |
+-------------------------------+
6. Instrukcja krok po kroku
6.1. 1. Utworzenie konta na SourceHut
Otwórz przeglądarkę i przejdź pod adres:
Wypełnij formularz:
Pole |
Wartość przykładowa |
Username |
|
|
|
Password |
(minimum 12 znaków, unikalne) |
Po wysłaniu formularza na podany adres email przyjdzie link weryfikacyjny. Kliknij go — konto zostanie aktywowane.
Po zalogowaniu zobaczysz dashboard meta.sr.ht, z którego możesz przejść do
poszczególnych usług: git.sr.ht (repozytoria), builds.sr.ht (CI),
lists.sr.ht (listy mailingowe) itd.
6.2. 2. Wygenerowanie klucza SSH Ed25519
Nie używaj domyślnego klucza RSA/SHA-1 wygenerowanego przez ssh-keygen
bez parametrów. Ed25519 jest szybszy, bezpieczniejszy i krótszy.
$ ssh-keygen -t ed25519 -C "jan@example.com" -f ~/.ssh/id_ed25519_srht
6.2.1. Opis parametrów
-t ed25519-
Typ klucza. Ed25519 jest algorytmem z rodziny kryptografii krzywych eliptycznych (ECC). OpenSSH obsługuje go od wersji 6.5 (2014).
-C "jan@example.com"-
Komentarz do klucza. Standardowo umieszcza się adres email. Komentarz trafia do pliku
.pubi jest widoczny w authorized_keys serwera. Ułatwia identyfikację, który klucz do kogo należy. -f ~/.ssh/id_ed25519_srht-
Ścieżka pliku wyjściowego. Użycie osobnego pliku dla SourceHut (a nie domyślnego
id_ed25519) pozwala na zarządzanie wieloma kluczami dla różnych serwisów.
6.2.2. Przykładowy wynik
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/janek/.ssh/id_ed25519_srht
Your public key has been saved in /home/janek/.ssh/id_ed25519_srht.pub
The key fingerprint is:
SHA256:r4ND0mF1ng3rPr1ntEx4mpl3D4t4T0b3V3r1f13d jan@example.com
The key's randomart image is:
+--[ED25519 256]--+
| .o=+o.. |
| .o=*o. |
| . .+o+ |
| . o+ . |
| oS . . |
| . . + . |
| .oo+ = |
| +o+ X |
| ooB+E. |
+----[SHA256]-----+
6.2.3. Wyjaśnienie
-
Plik
id_ed25519_srht— klucz prywatny. NIGDY nie udostępniaj go nikomu. Powinien mieć prawa600(tylko odczyt dla właściciela). -
Plik
id_ed25519_srht.pub— klucz publiczny. Możesz go swobodnie udostępniać. To ten plik wkleisz do SourceHut. -
fingerprint(SHA256:…) — skrót klucza publicznego. Służy do weryfikacji tożsamości serwera (wknown_hosts) oraz identyfikacji klucza.
6.2.4. Passphrase
Hasło (passphrase) to dodatkowa warstwa ochrony klucza prywatnego. Jeśli klucz zostanie skradziony, bez passphrase’a jest bezużyteczny. Zaleca się stosowanie passphrase’a o długości co najmniej 12 znaków.
6.2.5. Cofnięcie
Usunięcie plików klucza:
$ rm ~/.ssh/id_ed25519_srht ~/.ssh/id_ed25519_srht.pub
Uwaga: jeśli klucz został już dodany do SourceHut, musisz go także usunąć z ustawień konta (patrz krok 3), inaczej stracisz dostęp do repo.
6.2.6. Typowe błędy
Jeżeli nie podasz passphrase’a podczas ssh-keygen, klucz prywatny będzie
zapisany niezaszyfrowany. Osoba, która zdobędzie dostęp do pliku, od razu
może go użyć.
Po fakcie możesz dodać passphrase do istniejącego klucza:
$ ssh-keygen -p -f ~/.ssh/id_ed25519_srht
Omówienie
-p — zmiana passphrase’a,
-f — wskazanie pliku klucza.
6.3. 3. Dodanie klucza publicznego do konta SourceHut
Zaloguj się na https://meta.sr.ht i przejdź do zakładki Keys (bezpośredni link: https://meta.sr.ht/keys).
Wyświetl zawartość klucza publicznego:
$ cat ~/.ssh/id_ed25519_srht.pub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKmJ... jan@example.com
Skopiuj całą linię (zaczyna się od ssh-ed25519 i kończy adresem email).
W interfejsie meta.sr.ht:
-
Kliknij Add a key.
-
W polu tekstowym wklej skopiowaną linię.
-
Opcjonalnie nadaj etykietę (np. "Laptop osobisty").
-
Kliknij Add.
6.3.1. Weryfikacja
Po dodaniu klucz pojawi się na liście w sekcji SSH Keys z fingerprintem i datą dodania.
6.3.2. Typowe błędy
Jeżeli skopiujesz klucz z kilkoma liniami lub dodatkowymi spacjami,
SourceHut odrzuci go. Użyj cat i zaznacz dokładnie jedną linię.
Jeżeli wcześniej wygenerowałeś klucz RSA bez -t ed25519, plik .pub
zaczyna się od ssh-rsa. To też zadziała, ale Ed25519 jest preferowany.
6.4. 4. Konfiguracja ~/.ssh/config
Plik ~/.ssh/config pozwala na precyzyjne sterowanie parametrami
połączenia SSH dla poszczególnych hostów. Dla SourceHut konfiguracja
pozwala wskazać konkretny klucz prywatny (ten dedykowany dla sr.ht) oraz
optymalizuje ustawienia.
$ cat >> ~/.ssh/config << 'EOF'
# SourceHut - git hosting
Host git.sr.ht
HostName git.sr.ht
Port 22
User git
IdentityFile ~/.ssh/id_ed25519_srht
IdentitiesOnly yes
PreferredAuthentications publickey
ServerAliveInterval 60
ServerAliveCountMax 3
EOF
6.4.1. Opis parametrów
Host git.sr.ht-
Nazwa hosta w konfiguracji SSH. Wszystkie kolejne parametry dotyczą tylko połączeń, gdy użytkownik wpisze
ssh git.sr.htlub Git użyje URLssh://git@git.sr.ht/…. HostName git.sr.ht-
Rzeczywista nazwa DNS serwera. Może być inna niż
Host, co pozwala na tworzenie aliasów (np.Host srht→HostName git.sr.ht). Port 22-
Port SSH (domyślnie 22, ale jawna deklaracja zapobiega błędom przy zmianie domyślnych ustawień w
/etc/ssh/ssh_config). User git-
Nazwa użytkownika SSH. SourceHut wymaga logowania jako
git— to jedyny użytkownik dostępny na serwerze. Autoryzacja odbywa się na podstawie klucza publicznego (który jest mapowany na Twoje konto). IdentityFile ~/.ssh/id_ed25519_srht-
Ścieżka do klucza prywatnego. Jeśli pominiesz tę opcję, SSH użyje domyślnych plików (
id_rsa,id_ed25519,id_ecdsa) w kolejności prób. Jawna deklaracja eliminuje domyślne próbowanie. IdentitiesOnly yes-
SSH ma używać tylko kluczy jawnie wskazanych w
IdentityFiledla tego hosta, ignorując klucze załadowane przezssh-agent. Kluczowe w środowiskach, gdziessh-agentma wiele kluczy i SourceHut odrzuca połączenie po kilku nieudanych próbach. PreferredAuthentications publickey-
SSH ma od razu przejść do uwierzytelniania kluczem publicznym, bez próbowania
password,keyboard-interactiveanihostbased. Przyspiesza połączenie. ServerAliveInterval 60-
Wysyłaj keepalive co 60 sekund. Zapobiega zrywaniu połączenia przez firewalle i NAT, które zamykają nieaktywne sesje.
ServerAliveCountMax 3-
Maksymalna liczba nieudanych prób keepalive. Po 3 minutach (60s * 3) braku odpowiedzi SSH kończy sesję.
6.4.2. Prawa dostępu do plików
$ chmod 600 ~/.ssh/config # tylko właściciel: rw
$ chmod 700 ~/.ssh # tylko właściciel: rwx
$ chmod 600 ~/.ssh/id_ed25519_srht
$ chmod 644 ~/.ssh/id_ed25519_srht.pub
6.4.3. Typowe błędy
IdentityFile wskazuje na nieistniejący plikSSH zgłosi błąd:
Warning: Identity file /home/janek/.ssh/id_ed25519_srht not accessible: No such file or directory.
Sprawdź czy plik istnieje i popraw ścieżkę w config:
$ ls -la ~/.ssh/id_ed25519_srht
IdentitiesOnly yes — zbyt restrykcyjne dla ssh-agentJeśli używasz ssh-agent z wieloma kluczami i potrzebujesz wszystkich,
usuń IdentitiesOnly yes lub skomentuj:
# IdentitiesOnly yes
6.4.4. Cofnięcie zmian
Usuń dodany blok z ~/.ssh/config ręcznie (edytor) lub:
$ sed -i '/^# SourceHut/,/^$/d' ~/.ssh/config
6.5. 5. Test połączenia SSH
Zanim przejdziesz do operacji Git, zweryfikuj, czy SSH łączy się prawidłowo.
$ ssh -T git@git.sr.ht
6.5.1. Opis
-T-
Wyłącza alokację pseudo-terminala (TTY). Nie potrzebujemy terminala — sprawdzamy tylko, czy uwierzytelnienie działa.
git@git.sr.ht-
Użytkownik
git, hostgit.sr.ht. Parametry połączenia zostaną odczytane z~/.ssh/config(jeśli mamy zdefiniowanyHost git.sr.ht).
6.5.2. Przykładowy wynik (poprawne połączenie)
Hi jan-kowalski! You've successfully authenticated, but SourceHut does not provide shell access.
Serwer potwierdza Twoją tożsamość (nazwa użytkownika), po czym zamyka połączenie — SourceHut nie daje dostępu do shella.
6.5.3. Przykładowy wynik (pierwsze połączenie — fingerprint serwera)
The authenticity of host 'git.sr.ht (2604:180:2::c)' can't be established.
ED25519 key fingerprint is SHA256:U7BFPNzWZBX80l7G24f7jG/4oHBoWAb7bGqYKy6vLEs.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
6.5.4. Weryfikacja fingerprintu serwera
Zweryfikuj, czy fingerprint jest poprawny. Aktualny fingerprint serwera znajdziesz na stronie:
(lub w repozytorium meta.sr.ht). Przykładowo dla połączeń IPv4 i IPv6 SourceHut używa następujących kluczy:
-
SHA256:U7BFPNzWZBX80l7G24f7jG/4oHBoWAb7bGqYKy6vLEs(ED25519)
Jeśli fingerprint się zgadza, wpisz yes. Klucz zostanie zapisany w
~/.ssh/known_hosts.
6.5.5. Wyjaśnienie
-
known_hosts— plik, w którym SSH przechowuje fingerprinty serwerów, z którymi nawiązałeś połączenie. Przy kolejnych połączeniach SSH porównuje fingerprint i ostrzega, jeśli się zmienił. -
Zmiana fingerprintu może oznaczać atak MITM (Man-In-The-Middle) lub reinstalację serwera. Zawsze weryfikuj przez inny kanał.
6.5.6. Typowe błędy (nieudane uwierzytelnienie)
git@git.sr.ht: Permission denied (publickey).
Przyczyny i rozwiązania
-
Klucz prywatny nie został dodany do agenta ani wskazany w
~/.ssh/config.-
Sprawdź
IdentityFilew konfiguracji. -
Sprawdź, czy
ssh-add -lpokazuje klucz.
-
-
Klucz publiczny nie został dodany do SourceHut.
-
Przejdź do https://meta.sr.ht/keys i zweryfikuj obecność klucza.
-
-
Złe uprawnienia pliku klucza.
-
Sprawdź:
ls -la ~/.ssh/id_ed25519_srht(powinno być-rw-------).
-
-
Błędny
Userw~/.ssh/config.-
SourceHut wymaga
User git. Użycie własnej nazwy użytkownika zakończy się błędem.
-
6.5.7. Cofnięcie zmian
Jeśli dodałeś fingerprint do known_hosts przez pomyłkę, usuń linię:
$ ssh-keygen -R git.sr.ht
6.6. 6. Utworzenie repozytorium na SourceHut
Przejdź do https://git.sr.ht i kliknij Create repository.
6.6.1. Formularz
Pole |
Opis |
Przykład |
Repository name |
Nazwa repozytorium (widoczna w URL) |
|
Description |
Krótki opis |
|
Visibility |
|
|
|
||
Default branch |
Gałąź domyślna |
|
Update method |
|
|
|
||
README |
Dodanie pliku README (opcjonalnie) |
|
License |
Wybór licencji (opcjonalnie) |
|
Po zatwierdzeniu otrzymasz URL repozytorium:
https://git.sr.ht/~jan-kowalski/moj-projekt
i SSH URL:
git@git.sr.ht:~jan-kowalski/moj-projekt
6.6.2. Opcje Update method
-
git push— standardowy push przez SSH. Każdy push jest natychmiast publikowany. -
email— zmiany przychodzą przez serie łat (patch series) na listę mailingową. SourceHut automatycznie aplikuje je po akceptacji. To domyślny workflow dla projektów wykorzystujących rozwój oparty na emailu (np. linux-kernel, git, alpine, sr.ht we własnym zakresie).
6.7. 7. Konfiguracja zdalnego repozytorium
Po utworzeniu repozytorium na serwerze skonfiguruj lokalnego Gita.
6.7.1. Inicjalizacja lokalnego repozytorium (jeśli nie istnieje)
$ mkdir -p ~/src/moj-projekt
$ cd ~/src/moj-projekt
$ git init
Initialized empty Git repository in /home/janek/src/moj-projekt/.git/
6.7.2. Dodanie plików i pierwszy commit
$ echo "# moj-projekt" > README.md
$ git add README.md
$ git commit -m "init: dodano README"
[trunk (root-commit) a1b2c3d] init: dodano README
1 file changed, 1 insertion(+)
create mode 100644 README.md
6.7.3. Dodanie zdalnego repozytorium
$ git remote add origin git@git.sr.ht:~jan-kowalski/moj-projekt
$ git remote -v
origin git@git.sr.ht:~jan-kowalski/moj-projekt (fetch)
origin git@git.sr.ht:~jan-kowalski/moj-projekt (push)
6.7.4. Opis polecenia
git remote add origin <url>-
Dodaje zdalne repozytorium o nazwie
origin(konwencja — może być dowolna).originto domyślna nazwa używana przez Git podczas push i pull, jeśli nie podano innej. git remote -v-
Wyświetla listę zdalnych repozytoriów z URL-ami.
-v(verbose) pokazuje zarówno URL fetch, jak i push.
6.7.5. Format URL SourceHut
git@git.sr.ht:~jan-kowalski/moj-projekt
-
git@git.sr.ht— użytkownikgitna hościegit.sr.ht. -
~jan-kowalski— tylda + nazwa użytkownika SourceHut. To nie jest rozwijanie~w katalog domowy — to konwencja SourceHut. -
moj-projekt— nazwa repozytorium.
6.7.6. Cofnięcie
$ git remote remove origin
6.8. 8. Pierwszy push
$ git push -u origin trunk
6.8.1. Przykładowy wynik
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 276 bytes | 276.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To git.sr.ht:~jan-kowalski/moj-projekt
* [new branch] trunk -> trunk
branch 'trunk' has been set up to track 'origin/trunk'.
6.8.2. Opis parametrów
-u(--set-upstream)-
Ustawia gałąź zdalną jako upstream dla bieżącej gałęzi. Dzięki temu przyszłe komendy
git pushigit pullmogą być wywoływane bez podawania nazwy zdalnego repozytorium i gałęzi. origin-
Nazwa zdalnego repozytorium (dodana wcześniej przez
git remote add). trunk-
Nazwa gałęzi lokalnej do wypchnięcia. SourceHut domyślnie używa
trunk(niemasteranimain).
6.8.3. Wyjaśnienie
-
Git najpierw kompresuje obiekty (commity, drzewa, bloby).
-
Przesyła je przez tunel SSH.
-
Serwer aktualizuje referencję gałęzi i odpowiada potwierdzeniem.
-
branch 'trunk' has been set up to track 'origin/trunk'— Git zapisał w konfiguracji lokalnej (branch.trunk.remote = origin,branch.trunk.merge = refs/heads/trunk).
6.8.4. Typowe błędy
remote: Repository not found: ~jan-kowalski/moj-projekt
fatal: repository 'git@git.sr.ht:~jan-kowalski/moj-projekt/' not found
Przyczyny
-
Repozytorium nie zostało utworzone na serwerze.
-
Nazwa użytkownika w URL jest niepoprawna.
-
Literówka w nazwie repozytorium.
Rozwiązanie
-
Sprawdź URL:
git remote -v. -
Odwiedź https://git.sr.ht/~jan-kowalski/ i sprawdź czy repo istnieje.
6.8.5. Cofnięcie
Nie ma prostego "undo" dla pusha. Jeśli chcesz usunąć zdalną gałąź:
$ git push origin --delete trunk
6.9. 9. Klonowanie repozytorium
$ git clone git@git.sr.ht:~jan-kowalski/moj-projekt
Cloning into 'moj-projekt'...
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.
6.9.1. Opis
git clone-
Tworzy lokalną kopię zdalnego repozytorium. Automatycznie:
-
Tworzy katalog o nazwie repozytorium.
-
Inicjalizuje
.git. -
Dodaje
originjako zdalne repozytorium. -
Pobiera (
fetch) wszystkie obiekty i referencje. -
Tworzy lokalną gałąź
trunkśledzącąorigin/trunk. -
Odpala
git checkout trunk(od wersji 2.38).
-
6.9.2. Klonowanie do konkretnego katalogu
$ git clone git@git.sr.ht:~jan-kowalski/moj-projekt ~/src/moj-projekt
6.9.3. Klonowanie tylko jednej gałęzi (płytkie)
$ git clone --depth 1 --branch trunk \
git@git.sr.ht:~jan-kowalski/moj-projekt
--depth 1-
Tylko ostatni commit — bez historii.
--branch trunk-
Klonuje konkretną gałąź (domyślnie domyślną gałąź zdalną).
6.9.4. Cofnięcie
Usuń sklonowany katalog:
$ rm -rf ~/src/moj-projekt
6.10. 10. Zarządzanie wieloma repozytoriami
SourceHut wspiera organizację pracy przez grupy repozytoriów. Każdy użytkownik może mieć dowolną liczbę repozytoriów. Dodatkowo istnieje możliwość tworzenia organizacji (teams).
6.10.1. Wiele repozytoriów w jednym projekcie
Utwórz osobne repozytorium dla każdego komponentu (backend, frontend, dokumentacja):
$ git remote add backend git@git.sr.ht:~jan-kowalski/moj-projekt-backend
$ git remote add frontend git@git.sr.ht:~jan-kowalski/moj-projekt-frontend
$ git remote add docs git@git.sr.ht:~jan-kowalski/moj-projekt-docs
6.10.2. Konfiguracja wielu kluczy SSH dla różnych serwisów
Jeśli masz konta na różnych serwisach Git (SourceHut, GitHub, własny
serwer), skonfiguruj ~/.ssh/config dla każdego:
# SourceHut
Host git.sr.ht
HostName git.sr.ht
User git
IdentityFile ~/.ssh/id_ed25519_srht
IdentitiesOnly yes
# GitHub
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
IdentitiesOnly yes
# Własny serwer Git
Host git.example.com
HostName git.example.com
Port 2222
User git
IdentityFile ~/.ssh/id_ed25519_example
IdentitiesOnly yes
6.10.3. Opis
-
Każdy
Hostdefiniuje osobny zestaw reguł. -
SSH dopasowuje
Hostna podstawie nazwy wpisanej w URL (np.git@github.comdopasujeHost github.com). -
Dzięki
IdentityFilekażdy serwis dostaje inny klucz — jeśli jeden klucz zostanie skompromitowany, pozostałe serwisy są bezpieczne.
6.10.4. Zarządzanie przez ~/.ssh/config z Include
Większe konfiguracje warto dzielić na pliki:
$ cat ~/.ssh/config
Include ~/.ssh/config.d/*
Host *
ServerAliveInterval 60
ServerAliveCountMax 3
$ mkdir -p ~/.ssh/config.d
$ cat > ~/.ssh/config.d/srht << 'EOF'
Host git.sr.ht
HostName git.sr.ht
User git
IdentityFile ~/.ssh/id_ed25519_srht
IdentitiesOnly yes
EOF
6.10.5. Cofnięcie
$ rm ~/.ssh/config.d/srht
6.11. 11. Konfiguracja domyślnej gałęzi i aliasów Git
SourceHut domyślnie używa gałęzi trunk. Dla wygody skonfiguruj aliasy:
$ git config --global init.defaultBranch trunk
$ git config --global alias.co checkout
$ git config --global alias.br branch
$ git config --global alias.ci commit
$ git config --global alias.st status
$ git config --global alias.lg "log --oneline --graph --all --decorate"
6.11.1. Wyjaśnienie
init.defaultBranch trunk-
Ustawia domyślną gałąź dla
git initnatrunk(zgodnie z konwencją SourceHut).
Aliasy skracają często używane komendy.
6.12. 12. Podpisywanie commitów (SSH)
SourceHut wspiera weryfikację commitów podpisanych kluczem SSH (od Git 2.34+). Jest to prostsze niż GPG i nie wymaga infrastruktury kluczy publicznych.
6.12.1. Generowanie klucza podpisu (jeśli nie masz)
Możesz użyć istniejącego klucza Ed25519 lub wygenerować osobny:
$ ssh-keygen -t ed25519 -C "jan@example.com" -f ~/.ssh/id_ed25519_sign
6.12.2. Konfiguracja Gita
$ git config --global gpg.format ssh
$ git config --global user.signingkey ~/.ssh/id_ed25519_sign.pub
$ git config --global commit.gpgSign true
6.12.3. Opis
gpg.format ssh-
Git ma używać SSH (a nie GPG) do podpisywania.
user.signingkey ~/.ssh/id_ed25519_sign.pub-
Ścieżka do klucza publicznego. Git odczyta klucz publiczny, ale do podpisu użyje odpowiadającego mu klucza prywatnego.
commit.gpgSign true-
Każdy commit będzie domyślnie podpisany (równoważne
git commit -S).
6.12.4. Dodanie klucza publicznego do SourceHut
Przejdź do ustawień https://meta.sr.ht/keys i dodaj klucz.
6.12.5. Test podpisu
$ git commit --allow-empty -m "test: podpis SSH"
$ git log --show-signature -1
6.12.6. Przykładowy wynik
commit a1b2c3d4e5f6...
Good "git" signature for janek with ED25519 key SHA256:...
Author: Jan Kowalski <jan@example.com>
Date: Mon Jul 20 12:00:00 2026 +0200
test: podpis SSH
Good "git" signature oznacza, że podpis jest poprawny.
6.12.7. Weryfikacja na SourceHut
Po pushu podpisany commit będzie oznaczony zieloną ikonką w interfejsie WWW.
6.12.8. Typowe błędy
error: cannot run ssh-keygen: No such file or directory
fatal: failed to write commit signature
Przyczyna
Git nie może znaleźć ssh-keygen (wymagane do wyodrębnienia klucza do
podpisu). Rozwiązanie:
# emerge --ask net-misc/openssh
6.12.9. Cofnięcie
$ git config --global --unset gpg.format
$ git config --global --unset user.signingkey
$ git config --global --unset commit.gpgSign
7. Omówienie wszystkich poleceń
7.1. ssh-keygen
Narzędzie OpenSSH do generowania, zarządzania i konwersji kluczy uwierzytelniania.
ssh-keygen [opcje] [-t typ] [-C komentarz] [-f plik_wyjściowy]
Opcja |
Opis |
|
Typ klucza: |
|
Komentarz (zwykle email) |
|
Ścieżka pliku wyjściowego |
|
Nowy passphrase (uwaga: widoczny w historii shella) |
|
Zmiana passphrase’a istniejącego klucza |
|
Wyświetlenie fingerprintu klucza |
|
Usunięcie hosta z known_hosts |
7.2. ssh
Klient SSH — program do łączenia się z serwerami SSH.
ssh [opcje] [user@]host [komenda]
Opcja |
Opis |
|
Wyłączenie alokacji TTY |
|
Tryb verbose (diagnostyka połączenia) |
|
Port (jeśli inny niż 22) |
|
Plik klucza prywatnego |
|
Opcja w formacie |
7.3. git clone
Klonowanie zdalnego repozytorium do lokalnego katalogu.
git clone [opcje] <url> [katalog-docelowy]
7.4. git remote
Zarządzanie zdalnymi repozytoriami.
git remote [-v | --verbose]
git remote add <nazwa> <url>
git remote remove <nazwa>
git remote rename <stara> <nowa>
git remote set-url <nazwa> <nowy-url>
7.5. git push
Wysyłanie commitów do zdalnego repozytorium.
git push [repozytorium] [gałąź]
git push -u origin trunk
7.6. git fetch
Pobieranie referencji i obiektów ze zdalnego repozytorium bez scalania.
git fetch [repozytorium]
git fetch --all
7.7. git pull
Pobranie i scalenie zmian ze zdalnego repozytorium.
git pull [repozytorium] [gałąź]
git pull jest równoważne git fetch + git merge FETCH_HEAD.
8. Weryfikacja poprawności
8.1. Lista kontrolna po konfiguracji
# 1. Klucz istnieje i ma poprawne uprawnienia
$ ls -la ~/.ssh/id_ed25519_srht
# 2. Klucz publiczny jest czytelny
$ cat ~/.ssh/id_ed25519_srht.pub
# 3. Konfiguracja SSH jest poprawna
$ ssh -T git@git.sr.ht
# Oczekiwane: "Hi ... You've successfully authenticated"
# 4. Zdalne repozytorium jest skonfigurowane
$ git remote -v
# 5. Push działa
$ git push -u origin trunk
# 6. Klonowanie działa (z innego katalogu, na próbę)
$ cd /tmp && git clone git@git.sr.ht:~jan-kowalski/moj-projekt && rm -rf moj-projekt
9. Diagnostyka
9.1. Zwiększenie poziomu szczegółowości SSH
Jeśli połączenie nie działa, uruchom SSH w trybie verbose:
$ ssh -vT git@git.sr.ht
Dla jeszcze większej szczegółowości:
$ ssh -vvvT git@git.sr.ht
9.1.1. Interpretacja wyjścia
Szukaj linii:
-
Authenticated to git.sr.ht ([…]:22)— sukces. -
Permission denied (publickey).— brak autoryzacji. -
Connection refused— serwer nie odpowiada (port zamknięty? firewall). -
Connection timed out— brak routingu do serwera.
9.2. Test DNS
$ host git.sr.ht
git.sr.ht has address 78.46.77.55
git.sr.ht has IPv6 address 2604:180:2::c
9.3. Test portu
$ nc -zv git.sr.ht 22
Connection to git.sr.ht (78.46.77.55) port 22 [tcp/ssh] succeeded!
9.4. Sprawdzenie agenta SSH
$ ssh-add -l
The agent has no identities.
Jeśli agent nie ma kluczy, dodaj:
$ ssh-add ~/.ssh/id_ed25519_srht
10. Typowe błędy
10.1. Permission denied (publickey)
Możliwa przyczyna |
Rozwiązanie |
Klucz nie dodany do konta |
Dodaj w https://meta.sr.ht/keys |
Zły klucz w IdentityFile |
Sprawdź |
Złe uprawnienia plików |
|
ssh-agent z nieprawidłowym |
Użyj |
kluczem (wiele kluczy) |
10.2. Repository not found
Możliwa przyczyna |
Rozwiązanie |
Repozytorium nie istnieje |
Utwórz na https://git.sr.ht |
Literówka w URL remote |
|
Brak tyldy przed nazwą użytkownika |
URL musi zaczynać się od |
Zła nazwa użytkownika |
Sprawdź w prawym górnym rogu dashboardu |
10.3. Konflikt z ssh-agent (odrzucenie klucza)
Objaw: pomimo poprawnego klucza, SSH odrzuca połączenie po kilku
próbach z różnymi kluczami. Przyczyna: ssh-agent próbuje kolejno
wszystkie załadowane klucze. Jeśli któryś z nich nie jest zaakceptowany
przez SourceHut, serwer może po kilku próbach zamknąć połączenie.
$ ssh -i ~/.ssh/id_ed25519_srht -o IdentitiesOnly=yes git@git.sr.ht
Dodaj IdentitiesOnly yes w ~/.ssh/config jak w kroku 4.
10.4. Zmiana nazwy użytkownika na SourceHut
Jeśli zmienisz nazwę użytkownika na SourceHut:
-
Wszystkie URL-e repozytoriów zmieniają się (musisz zaktualizować remote).
-
Klucze SSH są nadal powiązane z kontem — nie musisz ich zmieniać.
-
Zaktualizuj
~/.ssh/configjeśli używasz aliasów.
10.5. 100% CPU podczas git push (kompresja)
Git domyślnie używa wielu wątków do kompresji. Na słabszym sprzęcie możesz ograniczyć:
$ git config --global pack.threads 1
11. Dobre praktyki
11.1. Bezpieczeństwo kluczy
-
Nigdy nie udostępniaj klucza prywatnego. Pliki
id_ed25519,id_rsaitd. są prywatne. Nie wrzucaj ich do repozytoriów, nie przesyłaj przez komunikatory, nie wklejaj do terminala na streamingu. -
Używaj passphrase. Klucz bez passphrase’a to jak hasło zapisane na kartce przyklejonej do monitora. Jeśli laptop zostanie skradziony, attacker ma natychmiastowy dostęp do wszystkich serwisów.
-
Rotacja kluczy. Generuj nowy klucz co 12-24 miesiące. Stary klucz usuń z serwisów.
-
Osobne klucze dla różnych serwisów. Nigdy nie używaj tego samego klucza do SourceHut, GitHub i firmowego serwera Git. Kompromitacja jednego serwisu nie powinna wpływać na pozostałe.
-
Monitoruj dodane klucze. Regularnie przeglądaj listę kluczy na https://meta.sr.ht/keys. Nieznajomy klucz oznacza naruszenie konta.
11.2. Bezpieczeństwo Gita
-
Podpisuj commity. Użyj SSH signing (opisanego w kroku 12) lub GPG. Pozwala to zweryfikować, że commit pochodzi rzeczywiście od Ciebie.
-
Nie pushuj secrets. Nigdy nie wrzucaj haseł, tokenów API ani kluczy prywatnych do repozytorium. Użyj
.gitignorelub narzędzi jakgit-secrets,trufflehog. -
Sprawdzaj przed pushem. Użyj hooków
pre-pushdo walidacji.
11.3. Organizacja repozytoriów
-
Jedna nazwa, jeden cel. Każde repozytorium powinno mieć jasno określony zakres (jeden projekt, jeden komponent).
-
Konwencja nazewnicza. Używaj kebab-case:
moj-projekt-backend,moj-projekt-frontend. -
README. Każde repozytorium powinno zawierać README z opisem, instrukcją uruchomienia i budowania.
11.4. Praca z SourceHut
-
Używaj
trunkzamiastmaster/main. SourceHut domyślnie używatrunk. Jest to zgodne z filozofią platformy. -
Rozważ workflow oparty na emailu. SourceHut został zaprojektowany z myślą o rozwoju przez serie łat. Lists.sr.ht i Mail zintegrowane z Gitem dają pełną kontrolę nad historią projektu.
-
Backupuj repozytoria. SourceHut to usługa — nie traktuj jej jako jedynej kopii. Regularnie wykonuj
git clone --mirrorlub używaj drugiego zdalnego repozytorium jako backupu.
11.5. Backup repozytoriów
# Mirror (pełna kopia, wszystkie gałęzie, tagi)
$ git clone --mirror git@git.sr.ht:~jan-kowalski/moj-projekt \
/backup/moj-projekt.git
# Aktualizacja mirrora
$ cd /backup/moj-projekt.git && git fetch --all
12. Bezpieczeństwo
12.1. Ataki na klucze SSH
Zagrożenie |
Mitigacja |
Kradzież klucza prywatnego |
Passphrase, szyfrowanie dysku, |
ograniczone zaufanie do hosta |
|
Atak MITM (podmiana fingerprintu) |
Weryfikacja fingerprintu przez |
inny kanał (HTTPS, DNS, osobisty kontakt) |
|
Klucz pozostawiony w ssh-agent |
|
|
|
Użycie słabego algorytmu |
Tylko Ed25519 (RSA 4096 jako fallback) |
12.2. Firewall i sieć
-
SSH używa portu 22/TCP. Jeśli pracujesz za firewallem korporacyjnym, upewnij się, że ruch do
git.sr.ht:22jest dozwolony. -
Rozważ użycie
ProxyJumpprzez bastion host, jeśli bezpośrednie połączenie nie jest możliwe.
12.3. Monitoring podejrzanej aktywności
-
SourceHut wysyła powiadomienia email o nowych kluczach dodanych do konta.
-
Regularnie sprawdzaj logi SSH po stronie klienta:
journalctl -u sshd(jeśli masz serwer SSH) lub~/.ssh/known_hostspod kątem nieznajomych wpisów.
13. Podsumowanie
Niniejszy podręcznik przeprowadził Cię przez pełny cykl pracy z
SourceHut — od założenia konta, przez generowanie kluczy SSH Ed25519,
konfigurację ~/.ssh/config, test połączenia, utworzenie i zarządzanie
repozytoriami Git, aż po podpisywanie commitów i diagnostykę.
SourceHut różni się od popularnych platform (GitHub, GitLab) przede wszystkim:
-
obowiązkowym uwierzytelnianiem SSH,
-
minimalistycznym interfejsem,
-
priorytetyzacją poczty elektronicznej jako kanału współpracy.
Znajomość tych różnic i umiejętność poprawnej konfiguracji SSH jest kluczowa dla sprawnej pracy z tą platformą.
14. Checklista
-
✓ Konto na SourceHut utworzone i zweryfikowane
-
✓ Klucz SSH Ed25519 wygenerowany (
ssh-keygen -t ed25519) -
✓ Klucz publiczny dodany do https://meta.sr.ht/keys
-
✓
~/.ssh/configskonfigurowany (IdentityFile, IdentitiesOnly) -
✓ Uprawnienia plików poprawne (
~/.ssh: 700, klucze:600,.pub: 644) -
✓ Test połączenia SSH zaliczony (
ssh -T git@git.sr.ht) -
✓ Repozytorium utworzone na https://git.sr.ht
-
✓ Lokalne repozytorium zainicjalizowane (
git init) -
✓ Zdalne repozytorium dodane (
git remote add origin) -
✓ Pierwszy push wykonany (
git push -u origin trunk) -
✓ Klonowanie działa (
git clone) -
✓ Podpisywanie commitów skonfigurowane (opcjonalne)
15. Najczęstsze problemy
15.1. Nie mogę się zalogować do SourceHut
-
Sprawdź czy konto jest aktywowane (link w emailu).
-
Użyj opcji "Reset password" na https://meta.sr.ht.
-
Jeśli problem leży po stronie uwierzytelniania SSH, zacznij od
ssh -vT git@git.sr.ht.
15.2. git push wymaga hasła — ale SSH nie pyta
Jeśli SourceHut pyta o hasło zamiast uwierzytelnić kluczem, prawdopodobnie używasz URL HTTP zamiast SSH. Sprawdź:
$ git remote -v
URL powinien zaczynać się od git@git.sr.ht: — nie https://.
15.3. Webhook nie działa
SourceHut wspiera webhooki przez builds.sr.ht i listy mailingowe, ale nie
ma wbudowanego systemu webhooków jak GitHub. Do automatyzacji używaj
builds.sr.ht (CI/CD).
15.4. Brak wsparcia dla pull requestów
SourceHut nie ma pull requestów w znanym z GitHub znaczeniu. Zamiast tego używa:
-
Serii łat (patch series) — wysyłasz commity przez email na listę mailingową projektu.
-
Pull request przez email —
git request-pullgeneruje list zmian.
Alternatywnie możesz skonfigurować osobne gałęzie i pushować je do zdalnego repozytorium, a następnie poprosić maintainera o wciągnięcie zmian.
16. Dalsza lektura
-
Oficjalna dokumentacja SourceHut: https://man.sr.ht
-
Poradnik SSH (Gentoo Wiki): https://wiki.gentoo.org/wiki/SSH
-
Poradnik Git (Gentoo Wiki): https://wiki.gentoo.org/wiki/Git
-
Poradnik SSH (Arch Wiki): https://wiki.archlinux.org/title/SSH_keys
-
Poradnik Git (Arch Wiki): https://wiki.archlinux.org/title/Git
-
OpenSSH Cookbook: https://www.openssh.com/manual.html
-
SourceHut na GitHub (kod źródłowy): https://github.com/sircmpwn
-
Diffie-Hellman i bezpieczeństwo SSH: https://stribika.github.io/2015/01/04/secure-secure-shell.html
-
Pro Git (książka, oficjalna): https://git-scm.com/book/pl/v2
17. Najlepsze praktyki produkcyjne
-
Używaj kluczy Ed25519 z passphrasem. Żadnych kluczy RSA 2048 bez hasła. W środowisku produkcyjnym rozważ klucze na tokenach sprzętowych (FIDO2, yubikey) z
ssh-keygen -t ed25519-sk. -
Separacja kluczy. Osobny klucz dla SourceHut, osobny dla CI, osobny dla deploymentu. W przypadku wycieku jednego klucza, strata jest ograniczona.
-
Automatyzacja z
ssh-agentz timeoutem. W skryptach CI/Cd nie przechowuj kluczy bez passphrase. Używaj ephemeral agent z:[source,bash] ---- eval $(ssh-agent -t 3600) # agent wygasa po 1h ssh-add ~/.ssh/id_ed25519_srht ----
-
Regularna rotacja kluczy. W środowisku korporacyjnym ustal politykę rotacji (np. co 6 miesięcy). Automatyzuj proces skryptem.
-
Backup mirror dla każdego repozytorium. SourceHut to usługa zewnętrzna. Utrzymuj lokalny mirror (bare repository) i regularnie synchronizuj.
-
Monitoruj logi SSH. Skonfiguruj syslog/auditd do logowania wszystkich prób użycia kluczy SSH. Alertuj na nieudane uwierzytelnienia.
-
Używaj
ssh-auditdo skanowania konfiguracji serwera. Nawet jeśli serwer jest zewnętrzny (SourceHut), warto wiedzieć, jakie algorytmy są wspierane:[source,bash] ---- # ssh-audit git.sr.ht ----
-
Nie ufaj domyślnej konfiguracji SSH. Sprawdź
/etc/ssh/ssh_configpod kątem dziedziczonych ustawień.~/.ssh/configzHost *może nadpisać globalne ustawienia.