Optimize CI pipeline to skip builds for documentation-only changes

[kingdonb]

Problem Statement

Currently, documentation-only changes (README updates, ADR additions, Jekyll configuration) trigger full ARM64 Talos image rebuilds in our CI pipeline. This wastes compute resources and creates unnecessary noise in build history.

Current Behavior

Any push to main triggers full build pipeline:

on:
  push:
    branches: [ main ]
    # No path filtering - docs changes trigger expensive builds

Impact:

• ~15-20 minute builds for trivial documentation updates
• Unnecessary GitHub Actions minutes consumption
• Cluttered container registry with identical images
• False positive "new build" notifications

Scope of Documentation Files

Files that should NOT trigger rebuilds:

docs/**              # All documentation
*.md                 # Markdown files (README, etc.)
_config.yml          # Jekyll configuration
index.md             # GitHub Pages homepage
CONTEXT-HANDOFF.md   # Project context

Proposed Solution

1. Path-Based Build Filtering

on:
  push:
    branches: [ main ]
    paths:
      - 'patches/**'
      - '.github/workflows/build-talos-images.yml'
      - '!docs/**'
      - '!*.md'
      - '!_config.yml'

2. Conditional Job Execution

jobs:
  check-changes:
    outputs:
      should-build: ${{ steps.changes.outputs.build }}
    steps:
      - uses: dorny/paths-filter@v2
        id: changes
        with:
          filters: |
            build:
              - 'patches/**'
              - '.github/workflows/**'

Expected Outcomes

• Documentation changes no longer trigger Talos image builds
• LATEST-BUILD.md only updates when actual builds occur
• Reduced CI costs and faster documentation iteration
• Cleaner container registry history
• Docs-only PRs can merge without triggering infrastructure changes

Implementation Considerations

1. Workflow Paths: Should we use paths or paths-ignore?
2. Exception Handling: What if docs include new build requirements?
3. LATEST-BUILD.md: Should it have a different update mechanism for docs-only changes?
4. GitHub Pages: Ensure docs-only changes still trigger Pages deployment

Test Cases

Should Trigger Builds:

• Patch file changes (patches/01-arm64-spin-tailscale.patch)
• Workflow changes (.github/workflows/build-talos-images.yml)
• New extensions or build logic

Should NOT Trigger Builds:

• ADR additions (docs/ADRs/ADR-004-new-decision.md)
• README updates (README.md)
• Jekyll config (_config.yml)
• Documentation fixes (docs/SESSION-LEARNINGS.md)

Related Context

• Current Workflow: .github/workflows/build-talos-images.yml
• Build Cost: ~15-20 minutes per unnecessary build
• Documentation Site: https://urmanac.github.io/cozystack-moon-and-back/

This optimization will improve developer experience and reduce infrastructure costs while maintaining proper build triggers for actual code changes.

[kingdonb]

🔄 Partial Progress - Docs Filtering Already Implemented

We already have path filtering in place to skip builds for documentation-only changes!

✅ Current Implementation

on:
  push:
    branches: [main]
    paths-ignore:
      - 'docs/**'
      - '!docs/**'
      - '!README.md'
      - '!TODO.md'
      - '!CONTEXT-HANDOFF.md'
      - '!**/*.md'
      - '!index.md'
      - '!_config.yml'
      - '!attic/**'

Result: Documentation changes already skip the expensive ARM64 builds.

🎯 What's Working

• ✅ Docs-only changes don't trigger Talos image builds
• ✅ README/Jekyll config updates skip CI
• ✅ ADR additions don't waste compute resources
• ✅ Reduced CI costs for documentation iteration

🔍 Remaining Work

The main optimization opportunity is now build caching rather than path filtering. Our matrix strategy builds are efficient, but could benefit from:

1. Docker layer caching for CozyStack base images
2. Artifact caching for repeated Makefile runs
3. Conditional job execution based on patch file changes

💡 Recommendation

Consider closing this issue as substantially complete and open a new one specifically focused on build caching optimizations if needed. The core path filtering is working well.

[kingdonb]

✅ CONFIRMED WORKING - Issue Resolved

Just validated this works perfectly! Screenshots were pushed to the repo and:

Results:

• ✅ No ARM64 build triggered (would be ~15-20 minutes)
• ✅ GitHub Pages deployed fast (18+10 seconds build+deploy)
• ✅ Website updated properly with new content
• ✅ Path filtering working exactly as intended

Evidence:

• Documentation changes (images, markdown) skip expensive Talos builds
• Pages deployment workflow runs independently and efficiently
• No wasted compute resources on docs-only changes

The optimization is complete and functioning perfectly.

Closing as resolved - docs-only changes now have fast, efficient deployments while preserving expensive builds only for actual code changes.