Integrating Netlify CMS with GitHub Repo in a Next.js Portfolio

Introduction

Managing content efficiently in a developer portfolio is crucial, especially when it includes blogs, project showcases, or updates. While headless CMS platforms like Contentful or Strapi are powerful, Netlify CMS offers a lightweight, Git-based alternative - perfect for static sites and portfolios hosted on platforms like Vercel or Netlify.

In my previous blog, I covered how to build a modern developer portfolio using Next.js and Tailwind CSS, laying the foundation for a performant and visually appealing site.

In this new post, I’ll walk you through how I integrated Netlify CMS with my private GitHub repository, structured a Git-based publishing workflow, and designed a custom editorial experience using config.yml.

---

🚀 Why Netlify CMS for a Next.js Portfolio?

• Open source & Git-based: Content is stored as Markdown/JSON files in your repo.
• No backend hosting required: It runs entirely on the frontend.
• Version control by default: Every content update is a Git commit.
• Customizable UI: You can create custom fields and collections that fit your site’s schema.

---

🧱 GitHub-Based Publishing Flow

Here’s how the publishing workflow works when integrating Netlify CMS with a private GitHub repo:

🔁 Flow Breakdown:

1. Netlify CMS runs in a separate Netlify project (netlify-cms-admin).
2. The CMS uses Netlify Identity + Git Gateway to authenticate and commit to GitHub.
3. Once logged in, any content update creates a Pull Request or direct commit to the main portfolio repo (saket-portfolio).
4. The portfolio repo (hosted on Vercel) is configured to rebuild automatically using Vercel Continuous Deployment

---

🔐 Setting Up for Private GitHub Repos - By using Netlify Identity

To make this work with a private GitHub repository, use Netlify Identity for authentication and Git Gateway to push commits:

✅ Steps to Integrate:

1.Deploy your netlify-cms-admin project to Netlify.

2.Enable Netlify Identity:

• Go to your Netlify dashboard → your site → Identity tab.
• Click “Enable Identity” and Invite users (optional).

3.Enable Git Gateway:

• Under Identity → Services → Git Gateway → Enable and connect your private GitHub repo.

4.Configure Netlify CMS to use Git Gateway:

backend:
  name: git-gateway
  branch: main

5.Configure media folder for uploads:

media_folder: public/uploads
public_folder: /uploads

6.Set up a Deployment in your Netlify project:

• Go to Netlify → Projects → Your Project → Configuration → Select Build & Deploy.
• Add your github respository.
• After that, you should be able to see "Your project is linked to a Git repository for continuous deployment" message.

---

🗂️ Custom Collections & Fields in config.yml

The config.yml file defines what content editors see and how it maps to your repo structure.

Here’s an example blog collection:

backend:
  name: git-gateway
  branch: main

media_folder: public/uploads
public_folder: /uploads

collections:
  - name: "blog"
    label: "Blog Posts"
    folder: "content/blog"
    create: true
    slug: "{{slug}}"
    fields:
      - { label: "Title", name: "title", widget: "string" }
      - { label: "Publish Date", name: "date", widget: "datetime" }
      - { label: "Slug", name: "slug", widget: "string" }
      - { label: "Excerpt", name: "excerpt", widget: "text" }
      - { label: "Cover Image", name: "coverImage", widget: "image" }
      - { label: "Tags", name: "tags", widget: "list", default: ["Next.js"] }
      - { label: "Body", name: "body", widget: "markdown" }

⚙️ Why It's Structured This Way:

• git-gateway: Works seamlessly with Netlify Identity for secure auth.
• media_folder: Ensures image uploads are stored in public/uploads (Next.js can serve them statically).
• collections: Organizes content types. In this case, a blog post.
• fields: Matches the expected structure in my MDX-rendered blog components.

---

✍️ Editorial Workflow for Teams or Solo Use

If you're working with collaborators (content writers, marketers, etc.), Netlify CMS with Identity enables:

• User authentication with email invites and role management.
• Draft publishing - save progress before publishing.
• Preview mode - with Next.js preview feature.
• Review process - integrate with GitHub PRs if needed.

This keeps content contributors productive without touching GitHub directly.

---

🔄 Triggering Rebuilds in the Portfolio

When a blog is published:

• Netlify CMS commits a new Markdown file to content/blog/.
• The change pushes to your private GitHub repo.
• GitHub triggers a Netlify Deployment that rebuilds your portfolio.
• The new content is live - thanks to ISR (Incremental Static Regeneration) or full rebuilds.

This keeps your site fresh with no manual redeploying.

---

🧩 Summary

Integrating Netlify CMS with a private GitHub repo in a Next.js portfolio provides:

• A user-friendly, Git-based editorial interface
• Full version control over content
• A secure auth flow using Netlify Identity
• Automated deploys via Netlify and Vercel continuous deployment
• Custom content types using config.yml

This setup is ideal for developers, technical writers, or solo creators who want content flexibility without managing a backend.

---

🛠️ Tools & Resources

• Netlify CMS
• Netlify Identity Docs
• Netlify Git Configuration
• Vercel Git Integration
• Git Gateway Docs
• Next.js ISR