GitHub Pages: libreng hosting ng website — paano mag-publish nang hakbang-hakbang

Ano ang GitHub Pages

Ang GitHub Pages ay libreng hosting ng static na website na nakapaloob sa GitHub. Iniimbak mo ang mga file ng site sa karaniwang Git repository, at ipinapamahagi ito ng GitHub sa HTTPS. Bawat git push sa tamang branch ay nag-a-update ng site, kaya hindi mo na kailangan ng FTP, control panel ng hosting, o manu-manong pag-upload ng file.

Sa paghahanap sa Filipino at English, iba-iba ang tawag sa serbisyong ito: «github pages», «github pages libre», «github hosting», at minsan «ano ang git pages». Pero ang tamang pangalan ay GitHub Pages: feature ito ng platform na GitHub, hindi ng Git mismo. Walang inilalathala ang Git; iniimbak lamang nito ang kasaysayan ng mga pagbabago.

Kadalasang ginagamit ang GitHub Pages para sa dokumentasyon ng mga proyekto, personal na pahina at portfolio, blog, landing page, mga proyektong pang-aral, at mga demo ng frontend na app gaya ng React, Vue, o Svelte matapos i-build.

Git pages: hosting para sa static na content

Ang susing salita ay static. Inihahatid ng GitHub Pages sa browser ang mga handang file: HTML, CSS, JavaScript, mga larawan, font, at JSON. Hindi ito marunong magpatakbo ng code sa server: hindi gumagana rito ang PHP, Python, o server-side na Node.js, at ang mga database. Kung kailangan ng site ang registration, shopping cart, o admin panel na may database, kakailanganin mo ang tradisyonal na hosting o cloud platform.

Gayunpaman, gumagana sa browser ang JavaScript gaya ng dati. Maaaring tumawag ang single-page app sa mga external na API, maaaring ipadala ang mga form sa pamamagitan ng third-party na serbisyo, at maaaring gawin sa client side ang paghahanap sa loob ng site.

Mga uri ng site sa GitHub Pages

May tatlong uri ng site ang GitHub Pages, at ang uri ang nagtatakda ng address.

Isa lang ang site ng user o organisasyon bawat account, pero maaaring marami ang site ng proyekto, isa bawat repository. Dapat eksaktong tugma ang pangalan ng repository ng personal na site sa iyong username sa GitHub: kung ivan-petrov ang login mo, ivan-petrov.github.io ang pangalan ng repository.

Para sa mga pampublikong repository, available ang Pages sa libreng plano. Ang pag-publish ng site mula sa private repository ay nangangailangan ng bayad na plano ng GitHub; ang na-publish na site ay makikita pa rin ng lahat sa internet.

Paano mag-publish ng site sa GitHub Pages nang hakbang-hakbang

Ituturo natin ang pinakasimpleng daan: handang HTML file, i-publish mula sa branch. Kailangan mo ng GitHub account at naka-install na Git.

Hakbang 1. Gumawa ng repository

Sa GitHub, gumawa ng bagong pampublikong repository. Para sa personal na site, pangalanan itong username.github.io; para sa site ng proyekto, kahit anong pangalan. Pagkatapos, i-clone ito at magdagdag ng pangunahing pahina:

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

Kailangang index.html ang pangalan ng pangunahing pahina (o index.md, o README.md — gagawin din itong pangunahing pahina ng GitHub). Mahalaga ang malaking at maliit na letra: hindi gagana ang Index.html.

Hakbang 2. Ipadala ang mga file sa GitHub

git add index.html
git commit -m "Unang pahina ng site"
git push origin main

Kung humingi ng username at password ang Git sa unang pagpapadala, gumamit ng personal access token o pag-sign in sa browser — hindi tinatanggap ang karaniwang password ng GitHub account para sa git push sa HTTPS.

Hakbang 3. I-on ang Pages sa settings

Buksan ang repository sa GitHub, pumunta sa Settings, at sa side menu piliin ang Pages. Sa seksyong Build and deployment, sa field na Source, piliin ang Deploy from a branch. Sa ibaba nito, piliin ang branch (karaniwang main) at folder: root / (root) o /docs. I-click ang Save.

Kapaki-pakinabang ang folder na /docs kapag may code ng proyekto ang repository, at ang site ng dokumentasyon ay nasa hiwalay na direktoryo sa tabi nito.

Hakbang 4. Hintayin ang pag-publish

Tumatagal ng ilang segundo hanggang ilang minuto ang pag-publish; sinasabi ng GitHub na maaaring abutin ng hanggang 10 minuto ang una. Makikita ang progreso ng build sa tab na Actions: lalabas ang proseso na pages build and deployment. Kapag natapos ito na may berdeng check, lalabas ang address ng site sa Settings → Pages.

Mula roon, simple na: nag-e-edit ka ng mga file, nag-commit, at git push — kusang nag-a-update ang site.

Pag-publish gamit ang GitHub Actions

Angkop ang pag-publish mula sa branch kapag handa na ang mga file sa repository. Pero kung kailangang i-build muna ang site — halimbawa ito ay app na gawa sa Vite, React, o generator tulad ng Hugo — mas mainam ang GitHub Actions bilang source. Sa Settings → Pages, sa field na Source, piliin ang GitHub Actions, at magmumungkahi ang GitHub ng handang template ng workflow.

Ganito ang itsura ng minimal na workflow para mag-publish ng static na file mula sa folder na dist pagkatapos ng build:

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

Inilalagay ang file sa .github/workflows/pages.yml. Pagkatapos ng git push, ini-install ng Actions ang mga dependency, binu-build ang proyekto, at inilalabas ang laman ng dist. Ang bentahe ng ganitong paraan ay ang repository ay nag-iimbak lamang ng source code, at hindi nagkakalat ng mga naka-build na file ang kasaysayan ng commit.

Karaniwang bitag ng mga site ng proyekto ang mga path. Nagbubukas ang site sa /pangalan-ng-repository/, pero ang build tool ay karaniwang tumuturo sa mga resource mula sa root na /. Bunga nito, naglo-load ang pahina nang walang style at script. Inaayos ito sa pamamagitan ng base path: sa Vite ito ang parameter na base: '/pangalan-ng-repository/', at may katulad na opsiyon ang ibang build tool.

Jekyll at mga static site generator

Kapag nag-publish ka mula sa branch, idinadaan ng GitHub bilang default ang mga file sa Jekyll — isang static site generator na nakasulat sa Ruby. Kaya maaari kang sumulat ng mga pahina sa Markdown, gumamit ng mga theme at template, at ang GitHub na mismo ang gagawa ng HTML. Para sa blog o dokumentasyon, kapaki-pakinabang ito: sumusulat ka ng mga .md na file, at ang theme ang bahala sa itsura.

Isang side effect: binabalewala ng Jekyll ang mga file at folder na nagsisimula sa underscore, halimbawa _next o _assets. Kung na-build ang site gamit ang ibang tool at kailangan ang mga ganitong folder, maglagay ng walang lamang file na .nojekyll sa root:

touch .nojekyll
git add .nojekyll
git commit -m "I-disable ang Jekyll"
git push

Ang iba pang generator — Hugo, Astro, Eleventy, MkDocs, Docusaurus — ay gumagana sa pamamagitan ng GitHub Actions: nagaganap ang build sa workflow, at pagkatapos ay ina-upload ang handang folder. Hindi alam ng GitHub Pages ang mga ito; kailangan lang nito ang mga huling file.

Paano ikonekta ang sarili mong domain sa GitHub Pages

Sapat na ang address na username.github.io para sa mga proyektong pang-aral, pero para sa portfolio o proyekto, mas mainam ang sarili mong domain. Dalawang panig ang koneksyon: sa registrar ng domain, at sa settings ng repository.

DNS settings

Para sa subdomain tulad ng www.example.com o blog.example.com, gumawa ng CNAME record na tumuturo sa username.github.io. Para sa root domain na example.com, gumawa ng A records na tumuturo sa mga IP address ng GitHub Pages:

185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153

Nasa dokumentasyon ng GitHub ang kasalukuyang listahan ng mga address, kasama ang IPv6 para sa AAAA records — suriin ito bago mag-setup. Mainam na i-setup ang parehong root domain at www: ire-redirect ng GitHub ang isa papunta sa isa.

Setup sa repository

Sa Settings → Pages, ilagay ang domain sa field na Custom domain at i-save. Kapag nag-publish mula sa branch, gagawa ang GitHub ng file na CNAME na may pangalan ng domain sa repository. Kapag nag-publish sa pamamagitan ng Actions, hindi kailangan ang file na CNAME, dahil nakaimbak ang domain sa mga setting.

Inirerekomenda ng GitHub na i-verify ang domain sa mga setting ng account (ang seksyong Pages sa mga profile setting): pinoprotektahan nito laban sa sitwasyon kung saan may ibang taong magkokonekta ng domain mo sa sarili niyang repository habang nakaturo pa sa GitHub ang DNS. Tumatagal nang hanggang isang araw bago kumalat ang mga pagbabago sa DNS, kaya kung hindi agad gumana ang domain, maghintay.

HTTPS sa GitHub Pages

Para sa mga address na *.github.io, laging naka-on ang HTTPS. Para sa sarili mong domain, awtomatikong nag-iisyu ang GitHub ng sertipiko ng Let's Encrypt kapag tama ang DNS. Pagkatapos nito, lalabas sa Settings → Pages ang checkbox na Enforce HTTPS — i-on ito para ma-redirect sa HTTPS ang lahat ng HTTP request.

Kung hindi mapili ang checkbox, hindi pa naiisyu ang sertipiko: suriin ang mga DNS record at maghintay. Minsan nakakatulong na burahin ang domain sa field na Custom domain at idagdag itong muli — sinisimulan nito ang muling pag-iisyu ng sertipiko. Tiyakin ding hindi kumukuha ng larawan o script ang site sa pamamagitan ng http://: haharangin ng browser ang mga ganitong resource bilang mixed content.

Mga limitasyon ng GitHub Pages

Libre ang hosting, pero may hangganan ito. Nakasulat ang mga ito sa dokumentasyon ng GitHub, at para sa karamihan ng personal at pang-aral na site, higit pa sa sapat ang mga ito.

Bukod sa mga teknikal na limitasyon, may mga patakaran sa paggamit: hindi nilalayon ang GitHub Pages para sa mga komersyal na serbisyo gaya ng online shop at SaaS, at hindi rin para sa pamamahagi ng malalaking file. Para sa portfolio, dokumentasyon, blog, at landing page ng proyekto — puwede.

Isa pang limitasyon ang kawalan ng server configuration. Walang sarili kang redirect, response header, o mga patakarang tulad ng .htaccess. Maaari ka lamang maglagay ng sariling pahinang 404.html sa root — ipapakita ito ng GitHub para sa mga address na hindi umiiral.

Mga karaniwang problema at paano ito ayusin

Error 404 sa GitHub Pages

Pinakakaraniwang dahilan ang kawalan ng file na index.html sa folder na napili bilang source. Tiyakin na tama ang napiling branch at folder (/ (root) o /docs), at na index.html ang pangalan ng file sa maliliit na letra. Pangalawang dahilan: hindi pa tapos ang pag-publish — tingnan ang tab na Actions at maghintay na matapos ang build.

Kung lumalabas ang 404 sa mga panloob na pahina ng single-page app kapag nire-refresh ang pahina, problema ito sa routing: hindi alam ng server ang address na /about dahil walang ganoong file. Ang mga paraan para malampasan ito ay hash routing (/#/about) o isang kopya ng index.html na pinangalanang 404.html.

Hindi nag-a-update ang site

Una, tiyakin na nakarating sa GitHub ang mga pagbabago: patakbuhin ang git status at git log origin/main --oneline -3. Pagkatapos, buksan ang tab na Actions: kung pumalpak ang build, may pulang krus doon at log na may error — halimbawa syntax error sa file ng Jekyll o error sa workflow.

Kung nagtagumpay ang build pero lumang bersyon pa rin ang nasa browser, ang cache ang may kasalanan. Nagka-cache ang GitHub Pages ng mga file nang ilang minuto, at nagka-cache din ang browser. I-refresh ang pahina habang nililinis ang cache (Ctrl+F5 o Cmd+Shift+R), o buksan ito sa private window.

Hindi naglo-load ang mga style at larawan

Halos palaging mali ang mga path. Sa site ng proyekto, ang link na /style.css ay tumuturo sa root ng username.github.io, hindi sa folder ng repository. Gumamit ng mga relative path (style.css, ./img/logo.png) o magtakda ng base path sa build tool. Suriin din ang mga letra sa pangalan ng file: pinagkakaiba ng mga server ng GitHub ang Logo.PNG at logo.png, kahit gumana ito sa lokal na Windows.

Nawawala ang mga folder na may underscore

Ito ang Jekyll: hindi nito inilalathala ang mga direktoryong gaya ng _app. Magdagdag ng file na .nojekyll sa root, o lumipat sa pag-publish gamit ang GitHub Actions.

Buod

Ang GitHub Pages ang pinakamabilis na paraan para mag-publish ng static na site nang libre: repository, file na index.html, source sa Settings → Pages — at ilang minuto lang, bukas na ang site sa username.github.io. Para sa mga site na may build, gamitin ang GitHub Actions; para sa sarili mong domain, ang DNS records at ang checkbox na Enforce HTTPS. Tandaan ang mga hangganan: static lamang, walang server code, at may limitasyon sa laki at trapiko. Ang pagtatrabaho sa GitHub, pagpapadala ng mga pagbabago, at automation ay detalyadong tinalakay nang praktikal sa kurso sa Git.