Devlog #4: Deployment & Development Debugging

Setting up GitHub Pages deployment with custom domains and implementing development-only debug patterns for better developer experience.

Published: May 26, 2025

From local development to live deployment: configuring GitHub Pages with custom domains and establishing patterns for development-only debugging that don’t interfere with production builds.

Going Live: GitHub Pages Deployment

After building my content management system and interactive components, it was time to deploy the Signals & Systems platform to the web. GitHub Pages emerged as the natural choice for hosting my Astro-based static site, offering seamless integration with my existing GitHub workflow.

GitHub Actions Workflow

The deployment process leverages GitHub Actions to automatically build and deploy my site whenever I push changes to the main branch. The workflow handles the entire pipeline from source code to live site.

name: Deploy to GitHub Pages

on:
push:
  branches: [ "main" ]
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: "pages"
cancel-in-progress: false

jobs:
build:
  name: Build
  runs-on: ubuntu-latest
  steps:
    - name: Checkout
      uses: actions/checkout@v4
    - name: Setup Node
      uses: actions/setup-node@v4
      with:
        node-version: "20"
    - name: Setup pnpm
      uses: pnpm/action-setup@v4
      with:
        version: 10
    - name: Install dependencies
      run: pnpm install
    - name: Build with Astro
      run: pnpm run build
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: ./dist

deploy:
  environment:
    name: github-pages
    url: ${{ steps.deployment.outputs.page_url }}
  needs: build
  runs-on: ubuntu-latest
  name: Deploy
  steps:
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

Custom Domain Configuration

Setting up custom domains involved both DNS configuration and GitHub Pages settings. I configured two domains to point to my GitHub Pages site: my primary domain and a shorter alternative.

// astro.config.mjs - Site URL configuration
export default defineConfig({
site: 'https://signalsandsystems.jellwrites.com',
integrations: [
  tailwind({
    applyBaseStyles: false,
  }),
  mdx(),
],
markdown: {
  shikiConfig: {
    theme: 'github-light',
    wrap: true
  }
}
});

The CNAME file in the public directory tells GitHub Pages which custom domain to use:

signalsandsystems.jellwrites.com

Build vs. Source Deployment

One key decision was whether to push the built dist folder or let GitHub Actions handle the build process. I chose the GitHub Actions approach for several reasons:

• Automation: Builds happen automatically on every push
• Consistency: Same build environment every time
• Clean Repository: No build artifacts in version control
• Easy Rollbacks: Can redeploy any previous commit

Development-Only Debug Patterns

As my platform grew more complex, I needed better visibility into what was happening during development without cluttering the production site with debug information.

Environment-Based Conditional Rendering

Astro provides import.meta.env.DEV to distinguish between development and production builds. This allows me to include helpful debug information that automatically disappears in production.

// Development-only debug information
{import.meta.env.DEV && (
<div class="debug-info">
  DEBUG: {articles.length} articles loaded
</div>
)}

Overlay Debug Styles

To prevent debug information from affecting page layout, I developed an overlay pattern using CSS positioning. This keeps debug info visible but completely separate from the content flow.

// Non-intrusive debug overlay
{import.meta.env.DEV && (
<div class="fixed top-4 right-4 bg-red-500 text-white px-2 py-1 text-xs rounded z-50 pointer-events-none">
  DEBUG: {articles.length} articles loaded
</div>
)}

The key CSS properties that make this work:

• fixed positioning removes the element from document flow
• z-50 ensures debug info appears above other content
• pointer-events-none prevents interference with user interactions
• Bright colors make debug content clearly identifiable

Common Debug Patterns

I established several reusable patterns for different types of debug information:

// Data count debug
{import.meta.env.DEV && (
<div class="fixed bottom-4 left-4 bg-blue-600 text-white px-2 py-1 text-xs rounded">
  {componentName}: {dataArray.length} items
</div>
)}

// State debug
{import.meta.env.DEV && (
<div class="absolute top-0 right-0 bg-yellow-500 text-black px-1 text-xs">
  State: {currentState}
</div>
)}

// Performance debug
{import.meta.env.DEV && (
<div class="fixed top-4 left-4 bg-green-600 text-white px-2 py-1 text-xs rounded font-mono">
  Render: {Date.now()}ms
</div>
)}

Updating Development Guidelines

To ensure consistent use of these patterns across the project, I updated my GitHub Copilot instructions to include comprehensive guidelines for development-only debug information.

Benefits of This Approach

• Zero Production Impact: Debug code is completely removed from builds
• Layout Preservation: Overlays don’t affect page structure
• Development Efficiency: Quick visual feedback during development
• Consistent Patterns: Standardized approach across components
• Performance Friendly: No runtime overhead in production

Deployment Workflow in Practice

The complete deployment process now works seamlessly:

1. Push changes to the main branch
2. GitHub Actions automatically triggers the build
3. Astro builds the static site with all debug code removed
4. The built site deploys to GitHub Pages
5. Custom domain serves the updated content

# Typical deployment command sequence
git add .
git commit -m "Add new article with debug overlays"
git push origin main

# GitHub Actions takes over:
# 1. Checkout code
# 2. Setup Node.js and pnpm
# 3. Install dependencies
# 4. Run build (import.meta.env.DEV = false)
# 5. Deploy to GitHub Pages
# 6. Update live site

Lessons Learned

Setting up deployment and debugging patterns taught me several valuable lessons:

• Automation Reduces Friction: Automated deployment encourages more frequent updates
• Environment Separation is Critical: Development and production should behave differently
• Visual Feedback Accelerates Development: Overlay debug info provides immediate insights
• Documentation Enables Consistency: Clear patterns prevent ad-hoc solutions

Looking Forward

My deployment pipeline is now production-ready, and my development debugging patterns provide the visibility I need without compromising the user experience. This foundation enables rapid iteration and confident deployments as I continue to expand the platform’s capabilities.

The combination of automated deployment and intelligent debugging represents a significant step forward in my development workflow, demonstrating how thoughtful tooling choices compound into major productivity gains.

JELL

Innovator, Educator & Technologist

GitHub LinkedIn

JELL is an innovator, educator, and technologist exploring the confluence of AI, higher education, and ethical technology. Through Signals & Systems, JELL shares insights, experiments, and reflections on building meaningful digital experiences, and other random things.

More about JELL →