GitHub Workflow and Build Process: A Comprehensive Guide

When developing software projects, maintaining code quality and ensuring consistency across your codebase is crucial. In this blog post, I'll explore the GitHub workflow and build process, powerful tools that can significantly improve your development experience, whether you're working in a team or on personal projects.

What is a GitHub Workflow?

A GitHub Workflow is an automated process defined in a YAML file (stored under .github/workflows/) that runs one or more jobs when specific events happen in your GitHub repository (like a push, pull request, or issue comment).
This automation is part of GitHub Actions, GitHub's built-in CI/CD (Continuous Integration/Continuous Delivery) platform. It allows you to automate various tasks like testing, building, and deploying your code directly from your GitHub repository.

What is a "Build"?

The build process is a crucial step where your source code is transformed into a deployable format. Depending on your project type.
Running pnpm build (or similar commands like npm run build or yarn build) executes this process locally before you commit your changes.

Why Running "Build" Before Committing is Important

As I learned during my HNG experience, running pnpm build before committing code is a best practice for several reasons:

• Early Error Detection: It identifies issues in your code before they reach the repository

• Performance Optimization: Catches potential performance issues
• Dependency Checks: Verifies all dependencies are properly installed
• Ensures Compatibility: Tests that your code works across different environments
• **Prevents CI Failures: **Avoids failing automated checks when you push to GitHub

Let me share a personal experience: After building a component and attempting to push to GitHub, my terminal displayed multiple warnings that could potentially break code upstream. If I had ignored these warnings and pushed anyway, the build would have failed on GitHub, preventing my code from being merged. By catching and fixing these errors locally first, I saved time and maintained the integrity of the codebase.

Are GitHub Workflows Good for Personal Projects?

Absolutely!, they are. i've started using it even on all personal projects. GitHub Workflows offer significant advantages:

• Help build professional habits and skills
• Keep your code robust and production-ready
• Save time as projects grow in size and complexity
• Make it easier to collaborate if you decide to expand the project

Complete CI GitHub Workflow Setup Guide

Now, let's walk through setting up a complete CI workflow for your project:
1. Setup Husky and Lint-Staged (Optional)
Husky allows you to use Git hooks, which run scripts before certain Git commands like commit or push.

pnpm add -D husky lint-staged

2. Initialize Husky
This creates a .husky folder and a .husky/pre-commit file:

pnpm dlx husky-init && pnpm install

3. Add a Pre-Push Hook
This runs linting and building before code is pushed to GitHub:

npx husky add .husky/pre-push "pnpm lint && pnpm build"

4. Setup ESLint (If Not Already Configured)
ESLint helps maintain code quality and consistency:
pnpm dlx eslint --init

5. Create GitHub Workflow Configuration
Create a .github/workflows directory in your project root and add a ci.yml file:
GitHub Workflow Configuration (ci.yml)
Note: this is just a sample, you can configure it to suit your project.

name: Lint and Build Check
on:
  pull_request:
    branches: [ main, dev ]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 'lts/*' # uses node latest version
      - name: Setup pnpm
        uses: pnpm/action-setup@v2
        with:
          version: '>=8.10.0'  # from version 8 upwards or you could use your preferred pnpm version
          run_install: false
      - name: Get pnpm store directory
        id: pnpm-cache
        shell: bash
        run: |
          echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
      - name: Setup pnpm cache
        uses: actions/cache@v3
        with:
          path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-store-
      - name: Install dependencies
        run: pnpm install
      - name: Run Lint
        run: pnpm lint
      - name: Run Build
        run: pnpm build

Let me break down this workflow file:
name: A descriptive name for your workflow
on: Specifies when the workflow should run (in this case, on pull requests to main or dev branches)
jobs: The tasks the workflow will perform
steps: Individual actions within each job:
Checkout the repository

• Setup Node.js
• Setup pnpm and configure caching
• Install dependencies
• Run linting
• Run the build process

6. Configure the Pre-commit Hook
Update the .husky/pre-commit file to run lint-staged:

#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

pnpm lint-staged

7. Enforce Protected Branch Rules
To ensure your workflow is enforced, configure branch protection in GitHub:

1. Go to your repository's Settings > Branches > Branch protection rules
   Add rules for main, dev, and other important branches

2. Enable these key settings:

3. Require status checks to pass before merging.

4. Select "Lint and Build Check" from available status checks

5. Require pull request reviews before merging
   Any other rules that meet your team's standards
   Important: Ensure your GitHub access token has workflow permissions to allow these checks to run.

## Understanding the Workflow Process
When this setup is in place, here's what happens:
1. Local development:

• You make changes to your code
• Before committing, husky runs lint-staged to check code quality
• Before pushing, husky runs linting and build to catch errors early 2. GitHub integration:
• When you create a pull request to main or dev
• GitHub Actions automatically runs your workflow
• The workflow checks out your code, installs dependencies, runs linting, and builds the project
• If any step fails, the pull request cannot be merged 3. Protected branches:
• Direct pushes to protected branches are prevented
• All code must pass through pull requests
• All pull requests must pass CI checks This ensures that only tested, validated code makes it into your important branches.

## Summary of Setup Steps

1. pnpm add -D husky lint-staged
2. pnpm dlx husky-init && pnpm install
3. npx husky add .husky/pre-push "pnpm lint && pnpm build"
4. pnpm dlx eslint --init (if needed)
5. Create .github/workflows/ci.yml
6. Configure branch protection rules Note: husky configuration is optional but can be very beneficial.

## Conclusion
Implementing GitHub workflows and proper build processes might seem like extra work initially, but the long-term benefits are substantial. These practices catch errors early, maintain code quality, streamline collaboration, and build professional habits that will serve you well throughout your development career.
Whether working on a team project or a personal portfolio piece, taking the time to set up these automated checks demonstrates your commitment to quality and professionalism.

Have you implemented GitHub workflows in your projects? What challenges did you face, and how did you overcome them? Share your experiences in the comments below!