October 30, 2023

Collaborative Power of GitHub Pages

Dive into the collaborative capabilities of GitHub Pages, a seamless platform for hosting and sharing software projects. In this guide, we'll walk through setting up GitHub Pages, automating deployments with GitHub Actions, and witnessing the fruits of your efforts.

In today's digital landscape, smooth collaboration plays a crucial role in any project's success. GitHub Pages emerges as a brilliant tool in this context, facilitating a straightforward way to host and showcase projects. What makes it stand out is its dual benefit: it's both a hosting platform and a collaborative tool. With GitHub Pages, static websites, documentation, or portfolios can be made accessible without a fuss. This ensures team members, stakeholders, and other viewers can track real-time updates without diving into complex setups. Let's see how you can harness this platform to uplift your collaborative efforts.

1. Setting up GitHub Pages

Your GitHub page comes with a unique HTTPS URL, a combination of your GitHub profile or organization and the repository name. This URL predominantly serves the project's static index.html. To get the ball rolling:

  1. Head to Settings -> Pages on GitHub.
  2. In the Build and deployment section, select Source -> Deploy from a branch -> gh-pages -> root.
  3. Confirm with "Save".

Once set, GitHub automatically refreshes your project whenever the gh-pages branch sees changes. You can view your project using the URL highlighted in the GitHub Pages section atop the settings page.

2. Automation with GitHub Actions

If you peek now, the gh-pages branch might appear barren. Let's address that by configuring a GitHub Action to auto-populate it.

GitHub Actions, integrated within GitHub, serve as a continuous integration mechanism. The goal is simple: draft an action script that pushes our app onto the gh-pages branch post its build. Here's a structured approach:

Begin by creating .github/workflows at the project's root, followed by a main.yml file. Here’s a practical layout:

name: Build and Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "14"

      - name: Install and build
        run: |
          npm install
          npm run build

      - name: Deploy to GitHub Pages
        uses: JamesIves/[email protected]
        with:
          folder: dist
          branch: gh-pages

In Brief:

  1. The action activates with every main branch push.
  2. Utilizing the ubuntu environment, it has the authority to push to gh-pages.
  3. The sequence covers code retrieval, Node.js environment preparation, dependency installation, app construction, and final deployment.

3. Witnessing Results

Upon committing to the main branch, observe the GitHub Action's progression under GitHub -> Actions. If the dist folder’s contents mirror gh-pages, your deployment hit the mark.

To bask in your project's live glory, head to https://your-username.github.io/your-repository/.

Wrapping Up

GitHub Pages is a fantastic blend of hosting and collaboration. By minimizing gaps between developers and stakeholders, it fosters a streamlined development environment. This guide aimed to simplify your journey with GitHub Pages. Feel free to share or seek insights in the comments. Until next time, happy coding!

References