Tofauti ya Git na GitHub kwa watumiaji wa VPS

GitHub ni nini?

GitHub ni huduma inayopangishwa (hosted service) inayohifadhi Git repositories na kujenga tovuti kuzunguka hazina hizo. Git ni programu ya kudhibiti matoleo (version control) inayofanya kazi kwenye kompyuta yako au seva yako mwenyewe. GitHub ni bidhaa ya kampuni moja iliyojengwa juu ya Git, inayomilikiwa na Microsoft tangu mwaka 2018. Unaweza kutumia Git kila siku bila kufungua GitHub hata mara moja. Huwezi kutumia GitHub bila Git.

Mstari huo ni muhimu wakati unamiliki VPS (virtual private server). Git ndiyo inayorekodi historia ya faili zako za usanidi (config files) na hati za kupeleka programu (deploy scripts). GitHub ni mahali ambapo nakala ya historia hiyo huishi wakati seva haipo, pamoja na kuwa mahali pa kuendesha builds na ukaguzi. Mwongozo huu unafuata mfano mmoja kuanzia folda tupu hadi kupeleka programu kwenye seva, na unafafanua kila neno jipya pale unapokutana nalo kwa mara ya kwanza.

Kile ambacho Git hufanya yenyewe

Git ni mfumo wa udhibiti wa matoleo (version control system): hurekodi hali ya saraka (directory) kadiri muda unavyopita, ili uweze kuona nini kilibadilika, lini, na kwa nini. Iliandikwa mwaka 2005 kwa ajili ya kazi ya Linux kernel. Ni mfumo uliogawanywa (distributed), kumaanisha kila nakala ya hazina (repository) inashikilia historia nzima. Hakuna seva kuu katika usanifu wake. Kompyuta ya mfanyakazi mwenzako ni nakala kamili kama ilivyo seva yoyote.

Isakinishe na uweke utambulisho wako. Git hukataa kurekodi commit bila jina na anwani ya barua pepe, kwa sababu vyote viwili huandikwa ndani ya commit yenyewe.

sudo apt update && sudo apt install -y git
git --version
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Kwenye Ubuntu 24.04, git --version huchapisha git version 2.43.0. Toleo lolote la miaka michache iliyopita hufanya kazi kwa njia ile ile kwa kila kitu kilicho hapa chini.

Mfano: hazina (repository) kwa ajili ya faili zako za deploy kwenye VPS

Repository, ambayo kwa kawaida hufupishwa kama "repo", ni saraka (directory) inayofuatiliwa na Git. Inakuwa repository pale unapoendesha git init, ambayo hutengeneza folda iliyofichwa ya .git ndani yake. Folda hiyo ndiyo repository yenyewe. Ukifuta .git, utabaki na saraka ya kawaida isiyo na historia yoyote.

mkdir vps-deploy && cd vps-deploy
git init -b main
printf '.env\n*.key\n' > .gitignore

-b main huipa tawi la kwanza jina la main. Ukiacha amri hiyo, Git itachapisha dokezo refu kuhusu jina la tawi la msingi badala yake. .gitignore huorodhesha njia (paths) ambazo Git haipaswi kuzifuatilia kamwe. Andika faili yako ya siri (secrets file) ndani yake siku ya kwanza, kwa sababu faili iliyowahi kufanyiwa commit mara moja hubaki kwenye historia hata baada ya kuifuta, na kuiondoa ipasavyo inamaanisha kuandika upya kila commit iliyofuata.

Commits: kitengo cha historia

Sasa ongeza script na uirekodi.

printf '#!/bin/sh\nsudo systemctl restart caddy\n' > restart.sh
git add restart.sh .gitignore
git commit -m "Add restart script and gitignore"
git log --oneline

git add huhamisha mabadiliko kwenye staging area, ambayo ni orodha ya vitu vitakavyoingia kwenye commit inayofuata. git commit huandika orodha hiyo kwenye historia kama ingizo moja. Commit huhifadhi snapshot ya kila faili inayofuatiliwa, ujumbe, mwandishi, timestamp, na pointer inayoelekeza kwenye commit iliyotangulia. git log --oneline huchapisha mstari mmoja kwa kila commit, kila mmoja ukianza na hash fupi kama vile a1b2c3d. Hash hiyo ndiyo jina la commit, na karibu kila amri ya Git huikubali.

Ruka hatua ya git add na git commit itajibu no changes added to commit (use "git add" and/or "git commit -a"). Hakuna kilichoharibika. Git inakuambia kuwa staging area haina kitu, kwa hivyo hakuna cha kupiga snapshot. git status ni amri ya kutumia wakati wowote unapopotea: inataja branch ya sasa, mabadiliko yaliyopo kwenye staging, na faili ambazo Git inaweza kuziona lakini haizifuatilii.

Branches: mstari wa pili wa historia

Branch ni kielekezi kinachotembea kuelekea kwenye commit. main ni branch, na haina sifa yoyote ya kipekee ndani ya Git. Kuunda branch hakugharimu chochote, kwa sababu Git huandika kielekezi kipya badala ya kunakili faili zako.

git switch -c add-backup
printf '#!/bin/sh\nrestic backup /srv\n' > backup.sh
git add backup.sh
git commit -m "Add nightly backup"
git switch main
ls

Baada ya git switch main, backup.sh haionekani kwenye orodha. Hakuna kilichofutwa. Faili hiyo ipo kwenye branch ya add-backup, na main haikuwahi kuwa nayo, kwa hivyo Git iliondoa faili hiyo kwenye saraka yako ya kazi ulipohama. Hili huwashangaza watu wote mara ya kwanza. git switch add-backup huirejesha.

Remotes: mahali ambapo GitHub hatimaye inaonekana

Kila kitu hadi sasa kimefanya kazi kwenye mashine moja bila mtandao wowote. Remote ni URL yenye jina kwa ajili ya nakala nyingine ya hazina (repository) ileile. GitHub hukuhifadhia moja ya nakala hizo. Jina la kawaida kwa remote kuu ni origin.

Tengeneza hazina tupu kupitia tovuti ya GitHub, kisha unganisha nayo. Pendelea SSH badala ya HTTPS hapa: SSH key ni faili unalolimiliki, na halimalizi muda wake kama vile personal access token.

ssh-keygen -t ed25519 -C "vps-deploy"
cat ~/.ssh/id_ed25519.pub
ssh -T git@github.com

Bandika (paste) public key iliyochapishwa kwenye ukurasa wa SSH keys wa akaunti yako ya GitHub, kisha endesha jaribio hilo tena. Key inayofanya kazi hujibu Hi yourname! You've successfully authenticated, but GitHub does not provide shell access.. GitHub haikupi shell, kwa hiyo kukataliwa huko ndiko kunakoashiria mafanikio. git@github.com: Permission denied (publickey). inamaanisha key yako haikutumwa au haikukubaliwa, kwa hiyo hakikisha ulibandika faili la .pub na si private key iliyo pembeni yake.

git remote add origin git@github.com:yourname/vps-deploy.git
git push -u origin main

git push hutuma commits zako kwenye remote. -u hurekodi kuwa main ya ndani inafuatilia main ya remote, ili baadaye git push tupu itoshe. git clone <url> ni kinyume chake kwenye mashine mpya: hunakili hazina nzima pamoja na historia yake na kukuwekea origin. Remote ya HTTPS inafanya kazi pia, na husafiri kupitia itifaki ileile kama ukurasa wowote wa wavuti, jambo linalosaidia kwenye mitandao inayozuia port 22 ya kutoka nje. Ikiwa sentensi hiyo inahitaji ufafanuzi zaidi, kile ambacho HTTP request kimeundwa nacho hasa kinaelezea mbinu hizo.

Pull requests, issues na forks: vipengele vya GitHub, si vya Git

Kila kitu hapo juu ni Git, na hufanya kazi na seva yoyote. Maneno matatu hapa chini ni vipengele vya GitHub. Wasimamizi wengine wa hazina (hosts) huiga vipengele hivi, na Git yenyewe haijui chochote kuzihusu.

Pull request (PR) ni ombi la kuunganisha branch moja na nyingine, lililowekwa kwenye ukurasa kwa ajili ya majadiliano. Unapush add-backup, unafungua PR dhidi ya main, na tovuti huonyesha tofauti za commit kwa commit. Watu hutoa maoni kwenye mistari mahususi. Ukaguzi wa kiotomatiki huripoti kufaulu au kufeli kwa branch hiyo. Bofya merge na GitHub hufanya uunganishaji kwenye nakala yake yenyewe, kisha husasisha main. Jina hili linatokana na mtiririko wa kazi wa awali, ambapo ulimwomba mtunzaji wa mradi avute (pull) branch yako kwenda kwenye yao.

Issue ni mjadala wenye namba kwa ajili ya mdudu (bug) au kazi. Hii hukaa kwenye database ya GitHub, si kwenye repository yako, jambo ambalo ni muhimu kujua kabla ya kuchagua host: ukiclone repo utapata kila commit, lakini si issue hata moja. Ili kutoa issue nje lazima utumie API.

Fork ni nakala yako ya seva ya repository ya mtu mwingine. Unakuwa na ruhusa ya kuandika kwenye nakala hiyo, unapush branch kwenda huko, na unafungua pull request kutoka kwenye nakala yako kurudi kwenye yao. Hivi ndivyo unavyoweza kuchangia kwenye mradi ambao watunzaji wake hawajawahi kukusikia. Fork ni clone inayokaa kwenye GitHub na kukumbuka ilikotoka.

Programu husoma vipengele vyote vitatu kupitia API ileile inayotumiwa na binadamu. Wakala wa ukaguzi wa pull request unaouendesha kwenye seva yako mwenyewe hufuatilia PR mpya, husoma diff, na kuweka maoni kwenye mistari. Miongozo kama faili la AGENTS.md kwenye mzizi wa repository ipo kwa sababu repo sasa husomwa na zana pamoja na binadamu.

Kile ambacho GitHub hufanya kwa mmiliki wa VPS

Anza na hifadhi ya nje ya seva. Skripti zako za deploy na playbooks zinapaswa kuwa mahali ambapo si kwenye seva inayosanidiwa. Jenga upya VPS kutoka kwenye image mpya, clone, kisha uendeshe. Weka repository hiyo ikiwa ya faragha na uipe seva deploy key: ufunguo wa SSH uliosajiliwa kwa repository moja badala ya akaunti yako yote, uliowekwa kuwa wa kusoma pekee (read-only). Deploy key ya read-only ikivuja, inafichua repo moja tu. Ufunguo wa akaunti ukivuja, unafichua kila kitu unachoweza ku-push.

sudo git clone git@github.com:yourname/vps-deploy.git /srv/vps-deploy
cd /srv/vps-deploy
git pull --ff-only

--ff-only inakataa kuunda merge commit. Kwenye seva inayopokea mabadiliko pekee, merge daima ni ajali, kwa hivyo flag hii inabadilisha historia yenye utata kuwa kosa la wazi la fatal: Not possible to fast-forward, aborting.. Kuna kitu kimebadilika kwenye seva ambacho hakikupaswa kubadilika. Kitafute kabla ya kufanya pull tena.

Fanya clone kama root kisha uendeshe Git kama mtumiaji mwingine na utapata fatal: detected dubious ownership in repository at '/srv/vps-deploy'. Git inakataa kusoma repository inayomilikiwa na mtumiaji tofauti, kwa sababu .git/config hasidi anaweza kuifanya Git iendeshe amri. Rekebisha umiliki kwa chown badala ya kuongeza ubaguzi wa safe.directory, kwa sababu ubaguzi huo huzima ukaguzi bila kuondoa chanzo cha tatizo.

GitHub Actions: njia za ujenzi na usambazaji (pipelines)

Actions ni mfumo wa CI/CD (continuous integration na continuous delivery) wa GitHub. Tuma (commit) faili la YAML ndani ya .github/workflows/ na GitHub italiendesha wakati tukio ulilolichagua linapotokea.

name: check
on:
  push:
    branches: [main]
jobs:
  shellcheck:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: sudo apt-get update && sudo apt-get install -y shellcheck
      - run: shellcheck *.sh

Faili hilo ni workflow. Job moja huendeshwa kwenye mashine moja. Step moja ni amri moja au action iliyochapishwa. uses: huleta action kutoka kwenye hazina (repository) nyingine, na @v7 hufunga toleo lake kuu (v7 ndilo la sasa kwa actions/checkout kufikia Agosti 2026). Daima funga toleo, kwa sababu action isiyofungwa inamaanisha kuwa msimbo ambao hujausoma unaendeshwa huku ukiwa na ufikiaji wa siri (secrets) zako.

runs-on: ubuntu-latest huomba GitHub ikupatie mashine pepe (virtual machine) mpya, ambayo hufutwa kazi inapokamilika. Mashine za kawaida (standard runners) ni bure kwenye hazina za umma, na mpango wa bure unajumuisha dakika 2,000 kwa mwezi kwa hazina za faragha kufikia Agosti 2026. Angalia ukurasa wa sasa wa bei kabla ya kupanga bajeti kulingana na takwimu hiyo.

Siri (secrets) huhifadhiwa kwenye mipangilio ya hazina na kusomwa kama ${{ secrets.DEPLOY_KEY }}. Workflow inayochochewa na pull request kutoka kwenye fork hupata token ya kusoma pekee (read-only) na haina ufikiaji wa siri hizo, kwa sababu vinginevyo mgeni anaweza kufungua PR ambayo kazi yake pekee ni kuzichapisha siri hizo.

Kukimbiza Actions runner kwenye VPS yako mwenyewe

runs-on: self-hosted hutuma kazi kwenye mashine unayomiliki badala yake. Ukurasa wa mipangilio ya runner wa hazina (repository) hukupa mstari wa kupakua, anwani ya wavuti ya hazina, na token ya usajili ambayo ni halali kwa saa moja. Weka hizo mbili za mwisho kwenye REPO_URL na RUNNER_TOKEN, kisha usanidi unakamilika kwa amri tatu.

./config.sh --url "$REPO_URL" --token "$RUNNER_TOKEN"
sudo ./svc.sh install
sudo ./svc.sh start
./svc.sh status

svc.sh status inapaswa kuripoti huduma kama inayofanya kazi na kuonyesha mistari ya hivi karibuni ya log. Runner hufungua muunganisho wa HTTPS wa kutoka kwenda GitHub na kuomba kazi, kwa hivyo hufungui mlango wowote wa kuingia (inbound port) kwa ajili yake. svc.sh install huandika unit ya systemd, na hii ndiyo hatua ambayo watu huruka: bila hiyo, runner hufungwa pamoja na kikao chako cha SSH na kila kazi inayofuata hukaa kwenye foleni bila maelezo. usanidi kamili wa runner inayojiendesha kwenye VPS hupitia hatua za kuimarisha usalama na usafishaji ambao runner ya muda mrefu inahitaji.

Faida yake ni kwamba deploy haihitaji tena SSH key ya kuingia inayoweza kufikiwa kutoka kwenye mtandao, kwa sababu kazi tayari inakimbia kwenye mashine hiyo. Akiba ya build (build cache) pia hubaki ikiwa tayari kati ya kazi, na hakuna kipimo cha dakika kinachohesabu.

Onyo moja si la hiari. Nyaraka za GitHub zenyewe zinapendekeza runners zinazojiendesha kwa hazina za faragha pekee, kwa sababu forks za hazina ya umma zinaweza kukimbiza msimbo hatari kwenye runner yako kwa kufungua pull request. Runner hutekeleza chochote ambacho faili ya workflow kwenye tawi hilo inasema. Kwenye hazina ya faragha ambapo unadhibiti nani anaweza kufanya push, hatari ni ndogo. Kwenye hazina ya umma, ichukulie runner yoyote inayojiendesha kama mashine ambayo wageni wanaweza kutekeleza msimbo juu yake.

Je, unahitaji GitHub hata kidogo?

Hapana. Git ndiyo kiwango cha kawaida, na GitHub ni huduma ya kurahisisha mambo tu. Forgejo na Gitea ni mifumo ya kujiendeshea (self-hosted) ya kuhifadhi msimbo, ambapo mfumo wa kuhifadhi msimbo ni seva ya Git iliyo na vipengele vya issues na pull requests. Zote mbili hutolewa kama binary moja ya Go, zote huendeshwa kwenye VPS ndogo, na Forgejo ni fork ya mwaka 2022 ya Gitea ambayo sasa inaendesha Codeberg. Kuhamisha repository ni amri moja tu, kwa sababu itifaki ya mawasiliano ni ileile.

git remote -v
git remote set-url origin git@git.example.com:you/vps-deploy.git
git push origin main

Kila commit huhamishika, kwa sababu kila clone tayari ina historia nzima. Kinachohamia si safu ya ziada ambayo GitHub ilijenga juu yake: threads za issues na pull requests. CI pia haihamishiki. Forgejo ina utekelezaji wake wa Actions unaosoma YAML inayofanana kutoka .forgejo/workflows/, na nyaraka zake ziko wazi kuhusu mipaka hiyo, zikieleza kuwa GitHub Actions na Forgejo Actions si sawa na mambo yanaweza yasifanye kazi mara moja. Pia inahitaji runner yake yenyewe. Panga hatua hiyo kama uhamiaji (port), siyo nakala rahisi.

Sababu ya kweli inayofanya miradi mingi kubaki huko ni wachangiaji. Msimbo wa hadhara lazima uwe mahali ambapo watu tayari wana akaunti. Scripts zako za binafsi za deploy hazihitaji kuwa huko. Hayo ni maamuzi mawili tofauti, na unaruhusiwa kuyajibu kwa njia tofauti.

Nini huvunjika kwanza, na ujumbe wa hitilafu unasema nini

Push inakataliwa. Unaona hivi:

 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:yourname/vps-deploy.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally.

Kitu fulani kimefanyiwa push tangu ulipofanya pull mara ya mwisho, mara nyingi ni marekebisho uliyofanya kwenye web editor. Tekeleza git pull --rebase ili kurudia commits zako juu ya zao, kisha fanya push tena. Epuka git push --force kwenye branch inayotumiwa na watu wengi, kwa sababu inafuta commits za wengine kutoka kwenye branch hiyo kwenye seva.

fatal: refusing to merge unrelated histories. Umetekeleza git init kwenye kompyuta yako na ukaruhusu GitHub kutengeneza repository yenye README. Historia hizo mbili hazishiriki commit yoyote, kwa hivyo Git haitakisia. Njia safi ya kurekebisha ni kufanya clone ya nakala ya GitHub kwenye folda mpya na kuhamisha faili zako ndani yake.

error: src refspec main does not match any. Branch uliyotaja haipo hapa. Kwa kawaida repository haina commits zozote hadi sasa, au branch yako inaitwa master. git branch --show-current inatatua hili.

Siri imefika kwenye commit. Badilisha credential hiyo sasa hivi. Ichukulie kama imewekwa hadharani kuanzia wakati ilipofanyiwa push, kwa sababu forks, mirrors na cached views zina nakala ambazo huna njia ya kuzifuta.

FAQ

Je, GitHub ni kitu kimoja na Git?

Hapana. Git ni programu ya udhibiti wa matoleo (version control) unayoisakinisha kwenye mashine, na inafanya kazi bila mtandao wala akaunti. GitHub ni huduma ya kibiashara inayohifadhi hazina (repositories) za Git na kuongeza kiolesura cha wavuti, mfumo wa issues, pull requests na CI juu yake. Git ilitolewa mwaka 2005 na GitHub ilizinduliwa mwaka 2008 ikijengwa juu ya Git. Unaweza kutumia Git milele bila GitHub. Kila kipengele cha GitHub kinategemea Git kwa nyuma.

Je, nahitaji akaunti ya GitHub ili kutumia Git kwenye VPS yangu?

Hapana. git init, git commit na git log hufanya kazi kwenye seva bila usanidi wowote wa mbali, jambo ambalo linatosha kufuatilia mabadiliko kwenye faili za /etc au kuendesha hati za deployment. Akaunti inakuwa na manufaa pale unapotaka nakala ya historia inayoweza kuishi nje ya seva hiyo, au mashine ya pili inayoweza ku-clone hazina hiyo. Mifumo ya kujihifadhia (self-hosted forges) kama Forgejo na Gitea hutimiza hitaji hilo kwenye vifaa unavyomiliki, na SSH remote ya kawaida inayoelekeza kwenye bare repository kwenye mashine nyingine hufanya kazi bila kuhitaji programu yoyote ya forge.

Pull request ni nini?

Pull request ni ombi la kuunganisha tawi (branch) moja na nyingine, likiwa na ukurasa wa majadiliano ulioambatishwa. Unasukuma (push) tawi, unafungua PR dhidi ya main, na mwenyeji huonyesha mabadiliko hayo kwa kila commit ili wakaguzi waweze kutoa maoni kwenye mistari mahususi na ukaguzi wa kiotomatiki uweze kuripoti kufaulu au kufeli. Hili ni kipengele cha GitHub badala ya kuwa cha Git, kwa hivyo Git yenyewe haina amri ya kufanya hivyo. Wenyeji wengine hutekeleza wazo hilohilo, wakati mwingine wakiliita merge request.

Je, niendeshe GitHub Actions runner kwenye VPS yangu mwenyewe?

Kwa hazina ya faragha (private repository), mara nyingi ndiyo. Kazi huendeshwa kwenye vifaa unavyolipia tayari, hakuna dakika zinazopigwa hesabu, akiba ya build (build cache) inabaki ikiwa tayari, na deployment haihitaji tena ufunguo wa SSH wa kuingia (inbound) uliowekwa wazi kwenye mtandao, kwa sababu runner huunganisha kwa nje (outbound) kuelekea GitHub na kuomba kazi. Kwa hazina ya umma (public repository), GitHub inashauri kutofanya hivyo: mtu yeyote anaweza ku-fork hazina yako na kufungua pull request ambayo workflow yake huendesha msimbo kwenye mashine yako.

Je, ninaweza kuhamisha hazina zangu kutoka GitHub baadaye?

Msimbo, ndiyo, kwa urahisi. Kila clone inashikilia historia kamili, kwa hivyo git remote set-url origin <new url> ikifuatiwa na push huhamisha kila kitu kilichomo kwenye commit. Kinachobaki nyuma ni safu inayomilikiwa na GitHub: issues, majadiliano ya pull request na historia ya Actions huishi kwenye hifadhidata yake, si kwenye folda yako ya .git. Zana za uhamiaji zinaweza kunakili issues kupitia API, na faili za workflow mara nyingi huhitaji kuhaririwa ili zifae CI ya mwenyeji mpya. Kuzingatia hilo ndiyo hoja ya kuweka nyaraka muhimu ndani ya hazina badala ya kwenye nyuzi za issues.