Boosting Developer Activity: Resolving GitHub Pages Deployments Stuck on Deleted Branches

One of the most frustrating roadblocks for any developer is when a seemingly simple deployment goes awry. For those leveraging GitHub Pages to host portfolios, documentation, or project sites, encountering a situation where your live site stubbornly refers to a deleted branch can significantly hinder developer activity and productivity. This common issue often stems from caching mechanisms within GitHub's deployment infrastructure, even after you've updated your settings.

A recent discussion on the GitHub Community forum highlighted this exact problem. A user, radhamanjunath1023-afk, found their GitHub Pages deployment stuck referencing a deleted branch, despite trying conventional fixes like resetting the deploying branch and re-selecting the main branch for environments. This scenario underscores the need for a precise, methodical approach to resolve such persistent deployment glitches.

Streamlining Developer Activity: A Step-by-Step Fix

Fortunately, community expert Kushagra-Bajpei provided a comprehensive solution that addresses the underlying caching issue. The key is to systematically reset the GitHub Pages configuration, forcing a fresh deployment cycle. This process is critical for maintaining smooth developer activity and ensuring your projects are always up-to-date.

Here’s the recommended sequence of steps to resolve GitHub Pages deployments stuck on deleted branches:

1. Disable GitHub Pages Completely

   This is the crucial first step to clear any lingering cached configurations. Navigate to your repository's settings:

   • Go to: Repository → Settings → Pages
   • Under “Build and deployment”:
   • Set Source to “None”
   • Click Save

   Wait 1–2 minutes to allow the changes to propagate.

2. Re-enable GitHub Pages

   Once disabled, you can re-configure GitHub Pages with the correct branch.

   • Still in Settings → Pages:
   • Set Source to “Deploy from a branch”
   • Select branch: main (or your desired deployment branch)
   • Select folder: /root (or /docs if you use that for your build output)
   • Click Save

3. Check Environments (Important)

   Ensure your environment settings correctly allow deployments from your target branch.

   • Go to: Settings → Environments → github-pages
   • Click Configure
   • Under “Deployment branches and tags” select “All branches” (or explicitly allow main)
   • Save changes

4. Trigger a Fresh Deployment

   A small, intentional change can prompt GitHub Pages to re-evaluate its deployment source.

   • Make a small commit to the main branch (for example, edit README.md and commit).
   • This action forces GitHub Pages to redeploy using the newly configured correct branch.

5. (Optional but Helpful) Clear Old Workflows

   If you previously used GitHub Actions for Pages, old workflows might interfere.

   • Go to the Actions tab
   • Cancel any stuck or failed Pages deployments related to the old branch.

After following these steps, GitHub Pages should stop referring to the deleted branch and deploy correctly from your specified branch. Remember that GitHub Pages updates are not always instantaneous; it can take a few minutes for settings changes and new deployments to fully apply and reflect on your live site. Implementing such systematic troubleshooting processes contributes positively to your engineering performance goals and overall developer activity by minimizing downtime and maximizing efficiency.