GitHub Pages: hosting ya bure kwa tovuti yako — jinsi ya kuchapisha hatua kwa hatua

GitHub Pages ni nini

GitHub Pages ni hosting ya bure ya tovuti tuli uliojengwa ndani ya GitHub. Unahifadhi faili za tovuti kwenye repository ya kawaida ya Git, na GitHub inazitoa kwa HTTPS. Kila git push kwenye tawi sahihi inasasisha tovuti, kwa hiyo hutahitaji FTP, paneli ya hosting wala kupakia faili kwa mkono.

Kwenye mtandao wa Kiswahili na Kiingereza, huduma hii inaitwa kwa njia nyingi: «github pages», «github pages bure», «github hosting», wakati mwingine «git pages ni nini». Lakini jina sahihi ni GitHub Pages: ni kipengele cha jukwaa la GitHub, si cha Git yenyewe. Git haichapishi chochote; inahifadhi historia ya mabadiliko tu.

Mara nyingi GitHub Pages hutumika kwa nyaraka za miradi, kurasa binafsi na portfolio, blogu, kurasa za kutua (landing pages), miradi ya kufundishia, na demo za programu za frontend kama React, Vue au Svelte baada ya kujengwa.

Git pages: hosting ya tovuti tuli (static)

Neno muhimu ni tuli. GitHub Pages inamtumia msomaji faili zilizokamilika: HTML, CSS, JavaScript, picha, fonti, JSON. Haiwezi kuendesha msimbo kwenye seva: PHP, Python, Node.js ya upande wa seva na hifadhidata hazifanyi kazi hapa. Ikiwa tovuti yako inahitaji usajili, kikapu cha ununuzi au paneli ya usimamizi yenye hifadhidata, utahitaji hosting ya kawaida au jukwaa la wingu.

Hata hivyo, JavaScript kwenye kivinjari inafanya kazi kama kawaida. Programu ya ukurasa mmoja inaweza kuwasiliana na API za nje, fomu zinaweza kutumwa kupitia huduma za watu wengine, na utafutaji ndani ya tovuti unaweza kufanywa upande wa mteja.

Aina za tovuti kwenye GitHub Pages

GitHub Pages ina aina tatu za tovuti, na aina inaamua anwani.

Akaunti moja inaweza kuwa na tovuti moja ya mtumiaji au shirika, lakini tovuti za miradi zinaweza kuwa nyingi, moja kwa kila repository. Jina la repository ya tovuti binafsi lazima lilingane kabisa na jina lako la mtumiaji kwenye GitHub: ikiwa jina lako ni amina-juma, repository inaitwa amina-juma.github.io.

Kwa repository za umma, Pages inapatikana kwenye mpango wa bure. Kuchapisha tovuti kutoka repository ya faragha kunahitaji mpango wa kulipia wa GitHub; tovuti iliyochapishwa bado inaonekana kwa kila mtu mtandaoni.

Jinsi ya kuchapisha tovuti kwenye GitHub Pages hatua kwa hatua

Tuanze na njia rahisi zaidi: faili za HTML zilizokamilika, kuchapisha kutoka tawi. Utahitaji akaunti ya GitHub na Git iliyosakinishwa.

Hatua ya 1. Unda repository

Kwenye GitHub unda repository mpya ya umma. Kwa tovuti binafsi iite username.github.io, kwa tovuti ya mradi jina lolote linafaa. Kisha iclone na uongeze ukurasa mkuu:

git clone https://github.com/username/username.github.io.git
cd username.github.io
echo "<h1>Habari, GitHub Pages</h1>" > index.html

Ukurasa mkuu lazima uitwe index.html (au index.md, au README.md — GitHub nazo pia itazigeuza kuwa ukurasa mkuu). Herufi kubwa na ndogo zina maana: Index.html haitafanya kazi.

Hatua ya 2. Tuma faili kwenye GitHub

git add index.html
git commit -m "Ukurasa wa kwanza wa tovuti"
git push origin main

Ukiona Git inaomba jina la mtumiaji na nenosiri mara ya kwanza, tumia token binafsi ya ufikiaji au kuingia kwa kivinjari — nenosiri la kawaida la akaunti ya GitHub halikubaliwi kwa git push kupitia HTTPS.

Hatua ya 3. Washa Pages kwenye mipangilio

Fungua repository kwenye GitHub, nenda kwenye Settings na kwenye menyu ya kando chagua Pages. Kwenye sehemu ya Build and deployment, kwenye uwanja wa Source chagua Deploy from a branch. Chini yake taja tawi (kwa kawaida main) na folda: mzizi / (root) au /docs. Bonyeza Save.

Folda ya /docs ni nzuri pale repository ina msimbo wa mradi, na tovuti ya nyaraka iko karibu nao kwenye folda tofauti.

Hatua ya 4. Subiri uchapishaji

Kuchapisha huchukua sekunde chache hadi dakika kadhaa; GitHub inaonya kwamba mara ya kwanza inaweza kuchukua hadi dakika 10. Maendeleo ya ujenzi yanaonekana kwenye kichupo cha Actions: kutakuwa na mchakato wa pages build and deployment. Ukimaliza kwa alama ya kijani, anwani ya tovuti itaonekana kwenye Settings → Pages.

Kuanzia hapo ni rahisi: unahariri faili, unafanya commit na git push — tovuti inajisasisha yenyewe.

Kuchapisha kupitia GitHub Actions

Kuchapisha kutoka tawi kunafaa wakati repository ina faili zilizokamilika. Lakini ikiwa tovuti inahitaji kujengwa kwanza — kwa mfano ni programu ya Vite, React au kizalishaji kama Hugo — chanzo cha GitHub Actions ni bora. Kwenye Settings → Pages, kwenye uwanja wa Source chagua GitHub Actions, na GitHub itakupa violezo vya workflow.

Workflow ndogo ya kuchapisha faili tuli kutoka folda ya dist baada ya ujenzi inaonekana hivi:

name: Deploy to Pages
on:
  push:
    branches: [main]
permissions:
  contents: read
  pages: write
  id-token: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - uses: actions/configure-pages@v5
      - uses: actions/upload-pages-artifact@v3
        with:
          path: dist
      - id: deployment
        uses: actions/deploy-pages@v4

Faili inawekwa kwenye .github/workflows/pages.yml. Baada ya git push, Actions inasakinisha utegemezi, inajenga mradi na kuweka yaliyomo ya dist hewani. Faida ya njia hii ni kwamba repository inahifadhi msimbo wa chanzo tu, na faili zilizojengwa hazichafui historia ya commit.

Mtego wa kawaida kwenye tovuti za miradi ni njia (paths). Tovuti inafunguka kwenye anwani /jina-la-repository/, lakini kijenzi kwa chaguo-msingi kinarejelea rasilimali kutoka mzizi /. Matokeo yake ukurasa unapakia bila mitindo wala skripti. Hili linatatuliwa kwa kuweka njia ya msingi: kwenye Vite ni parameta base: '/jina-la-repository/', na kwenye vijenzi vingine kuna chaguo linalofanana.

Jekyll na vizalishaji vya tovuti tuli

Unapochapisha kutoka tawi, GitHub kwa chaguo-msingi inapitisha faili kupitia Jekyll — kizalishaji cha tovuti tuli kilichoandikwa kwa Ruby. Kwa hiyo unaweza kuandika kurasa kwa Markdown, kutumia mada na violezo, na GitHub inazigeuza kuwa HTML yenyewe. Kwa blogu au nyaraka hii ni rahisi: unaandika faili za .md, na mada inashughulikia muonekano.

Athari moja ya upande: Jekyll inapuuza faili na folda zinazoanza na mstari wa chini, kwa mfano _next au _assets. Ikiwa tovuti imejengwa kwa zana nyingine na folda kama hizo zinahitajika, weka kwenye mzizi faili tupu la .nojekyll:

touch .nojekyll
git add .nojekyll
git commit -m "Zima Jekyll"
git push

Vizalishaji vingine — Hugo, Astro, Eleventy, MkDocs, Docusaurus — vinafanya kazi kupitia GitHub Actions: ujenzi unafanyika kwenye workflow, kisha folda iliyokamilika inachapishwa. GitHub Pages yenyewe haijui kuhusu hivyo; inahitaji tu faili za mwisho.

Jinsi ya kuunganisha domain yako kwenye GitHub Pages

Anwani username.github.io inafaa kwa miradi ya kujifunza, lakini kwa portfolio au mradi ni bora kutumia domain yako mwenyewe. Muunganisho unafanyika pande mbili: kwa msajili wa domain na kwenye mipangilio ya repository.

Mipangilio ya DNS

Kwa subdomain kama www.example.com au blog.example.com, unda rekodi ya CNAME inayoelekeza kwa username.github.io. Kwa domain ya mzizi example.com, unda rekodi za A zinazoelekeza kwenye anwani za IP za GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Orodha ya sasa ya anwani, pamoja na IPv6 kwa rekodi za AAAA, iko kwenye nyaraka za GitHub — ilinganishe kabla ya kusanidi. Ni vyema kusanidi domain ya mzizi na www zote mbili: GitHub itaelekeza anwani moja kwenda nyingine.

Mipangilio kwenye repository

Kwenye Settings → Pages, weka domain kwenye uwanja wa Custom domain kisha uhifadhi. Ukichapisha kutoka tawi, GitHub itaunda faili la CNAME lenye jina la domain kwenye repository. Ukichapisha kupitia Actions, faili la CNAME halihitajiki, kwa sababu domain inahifadhiwa kwenye mipangilio.

GitHub inapendekeza kuthibitisha domain kwenye mipangilio ya akaunti (sehemu ya Pages kwenye mipangilio ya wasifu): hii inalinda dhidi ya hali ambapo mtu mwingine anaunganisha domain yako na repository yake wakati DNS bado inaelekeza kwa GitHub. Mabadiliko ya DNS yanaenea hadi saa 24, kwa hiyo kama domain haifanyi kazi mara moja, subiri.

HTTPS kwenye GitHub Pages

Kwa anwani za *.github.io, HTTPS imewashwa muda wote. Kwa domain yako, GitHub inatoa cheti cha Let's Encrypt yenyewe mara DNS ikiwa sahihi. Baada ya hapo, kwenye Settings → Pages kinaonekana kisanduku cha Enforce HTTPS — kiwashe ili maombi yote ya HTTP yaelekezwe kwenye HTTPS.

Ikiwa kisanduku hakiwezi kubonyezwa, cheti bado hakijatolewa: angalia rekodi za DNS na usubiri. Wakati mwingine inasaidia kufuta domain kwenye uwanja wa Custom domain kisha kuiongeza tena — hii inaanzisha upya utoaji wa cheti. Pia hakikisha tovuti haipakui picha wala skripti kupitia http://: kivinjari kitazuia rasilimali kama hizo kama maudhui mchanganyiko (mixed content).

Mipaka ya GitHub Pages

Hosting hii ni ya bure, lakini ina mipaka. Imeelezwa kwenye nyaraka za GitHub, na kwa tovuti nyingi binafsi na za kufundishia inatosha kabisa.

Mbali na mipaka ya kiufundi, kuna sheria za matumizi: GitHub Pages hairuhusiwi kwa huduma za kibiashara kama maduka ya mtandaoni na SaaS, wala kwa kusambaza faili kubwa. Kwa portfolio, nyaraka, blogu na kurasa za kutua za mradi — karibu.

Kikwazo kingine ni kwamba hakuna usanidi wa seva. Hakuna uelekezaji wako, vichwa vya majibu wala kanuni za aina ya .htaccess. Unaweza tu kuweka ukurasa wako wa 404.html kwenye mzizi — GitHub itaionyesha kwa anwani zisizokuwepo.

Matatizo ya kawaida na jinsi ya kuyatatua

Kosa 404 kwenye GitHub Pages

Sababu inayotokea mara nyingi ni kukosekana kwa faili la index.html kwenye folda iliyochaguliwa kama chanzo. Angalia kwamba umechagua tawi sahihi na folda sahihi (/ (root) au /docs), na kwamba faili linaitwa index.html kwa herufi ndogo. Sababu ya pili ni kwamba tovuti bado haijachapishwa: angalia kichupo cha Actions na usubiri ujenzi umalizike.

Ikiwa 404 inatokea kwenye kurasa za ndani za programu ya ukurasa mmoja unapoonyesha upya ukurasa, tatizo ni uelekezaji: seva haijui anwani kama /about, kwa sababu faili kama hilo halipo. Njia za kupita ni uelekezaji kwa heshi (/#/about) au nakala ya index.html yenye jina 404.html.

Tovuti haisasishwi

Kwanza hakikisha mabadiliko yamefika kwenye GitHub: endesha git status na git log origin/main --oneline -3. Kisha fungua kichupo cha Actions: ikiwa ujenzi umeshindwa, kutakuwa na alama nyekundu na log yenye hitilafu — kwa mfano sintaksia kwenye faili la Jekyll au hitilafu kwenye workflow.

Ikiwa ujenzi umefaulu lakini kivinjari kinaonyesha toleo la zamani, chanzo ni cache. GitHub Pages inahifadhi faili kwa dakika kadhaa, pamoja na kivinjari chenyewe. Onyesha upya ukurasa ukipita cache (Ctrl+F5 au Cmd+Shift+R), au fungua kwenye dirisha la faragha.

Mitindo na picha hazipakii

Karibu kila mara ni njia zisizo sahihi. Kwenye tovuti ya mradi, kiungo /style.css kinaenda kwenye mzizi wa username.github.io, si kwenye folda ya repository. Tumia njia za jamaa (style.css, ./img/logo.png) au weka njia ya msingi kwenye kijenzi. Pia angalia herufi kubwa na ndogo kwenye majina: seva za GitHub zinatofautisha Logo.PNG na logo.png, hata kama kwenye Windows kompyuta yako ilifanya kazi.

Folda zenye mstari wa chini zimepotea

Hii ni Jekyll: haichapishi folda kama _app. Ongeza faili la .nojekyll kwenye mzizi, au hamia kuchapisha kupitia GitHub Actions.

Kwa ufupi

GitHub Pages ndiyo njia ya haraka zaidi ya kuweka tovuti tuli bure: repository, faili la index.html, chanzo kwenye Settings → Pages — na baada ya dakika chache tovuti inafunguka kwa username.github.io. Kwa tovuti zenye ujenzi tumia GitHub Actions, na kwa domain yako tumia rekodi za DNS na kisanduku cha Enforce HTTPS. Zingatia mipaka yake: ni tuli pekee, bila msimbo wa seva, na kwa kikomo cha ukubwa na trafiki. Kazi na GitHub, kutuma mabadiliko na uendeshaji otomatiki vimefafanuliwa kwa mifano halisi kwenye kozi ya Git.