How Should Teams Manage Branches for Jekyll Sites on GitHub

By -

Introduction

Many teams and organizations use Jekyll and GitHub Pages not only for personal blogs, but also to publish documentation, landing pages, and microsites. When multiple contributors are involved, the structure of your repository becomes critically important. One question that often arises is: how should a team manage the main and gh-pages branches when working with Jekyll?

In this article, we’ll explore collaborative workflows, branching strategies, and automation practices that allow teams to publish Jekyll sites efficiently on GitHub Pages while maintaining a clean and stable repository.

Challenges Faced by Teams When Using Jekyll

1. Confusion Over Branch Roles

Without clear conventions, team members may push changes to the wrong branch, modify compiled HTML by mistake, or create merge conflicts between source and output.

2. Lack of Deployment Automation

Manual builds become error-prone when multiple people work on a site. One missed build step could result in broken links or outdated content being published.

3. Visibility and Permission Control

Not every contributor should have access to modify production content. Some teams want to separate roles: writers create content, editors approve, and only maintainers deploy.

Branching Strategy for Teams

The most reliable and scalable branching strategy for collaborative Jekyll projects is the three-tier model:

1. main: Approved Source Code

This is the central branch that holds reviewed and approved Jekyll source code. All content here is ready to be published.

2. dev: Drafts and Collaboration

Writers and designers push their changes to the dev branch. Editors or maintainers review and merge changes into main after approval.

3. gh-pages: Compiled and Deployed Output

This branch contains only the built static files. It is auto-updated from main using CI tools like GitHub Actions.

How the Workflow Operates

Step-by-Step Example

  1. Writers submit a pull request to dev with new blog posts or content edits.
  2. Editors review and merge to main after testing locally.
  3. A GitHub Action automatically builds the Jekyll site and publishes it to gh-pages.
  4. Users visiting the site see the latest stable content.

Automated Deployment with GitHub Actions

Automation eliminates human error and keeps the team focused on content and structure. Here’s how a simple workflow might look:

Sample GitHub Action


name: Deploy Jekyll Site

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
      - run: gem install bundler jekyll
      - run: bundle install
      - run: bundle exec jekyll build -d site
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site
          publish_branch: gh-pages

Why This Branching Strategy Works for Teams

1. It Enforces Clear Roles

Writers never touch production files. Reviewers work in main, while CI handles publishing. This separation keeps workflows clean and prevents accidental overwrites.

2. It's Scalable

As your team grows, you can introduce more specific branches (e.g. feature/content-a) and implement GitHub’s protection rules on main and gh-pages.

3. It Allows Full Plugin Support

Because you're building the site yourself, you’re not limited to GitHub’s safe mode. You can use plugins for features like search, footnotes, diagrams, and more.

4. It Supports Preview Deployments

Want to preview PRs before merging? Use GitHub Actions to deploy every pull request to a temporary URL via services like Netlify or Vercel.

Best Practices for Collaborative Teams Using Jekyll

  • Document your contribution and branching process in a CONTRIBUTING.md file.
  • Use pull requests for all changes, even from core team members.
  • Enable branch protection on main and gh-pages.
  • Enforce review rules (e.g. at least one approving review).
  • Use status checks to ensure builds pass before merging.

Alternatives and Variations

Mono-Branch Strategy (for small teams)

If you're only 1-2 people, you can use just the main branch and deploy manually or automatically. This keeps things simple, but lacks scalability.

Split Repositories (advanced)

Some teams use two separate repositories: one for the source (private) and one for the built output (public). This allows stricter control but adds complexity in syncing.

Example: Jekyll-Based Docs for Internal Platform

A team building internal tools at a startup might have:

  • Writers adding new tutorials in _posts
  • Editors reviewing technical accuracy
  • CI/CD systems automatically updating gh-pages

This ensures the documentation is always accurate, reviewed, and in sync with platform updates — without relying on manual updates or exposing internal notes.

Conclusion

For collaborative teams working with Jekyll on GitHub Pages, branching strategy is not just a technical choice — it's a foundation for how people interact, contribute, and publish together.

The combination of dev, main, and gh-pages creates a clean, scalable, and automatable workflow that keeps your project organized, your team coordinated, and your website always up to date.

If you're building a team-driven blog, documentation site, or public platform — it's worth investing in this branching model early on to avoid chaos later.