May 25, 2026
—
## The Problem: The Stateless Container Timestamp Trap
When building a modular static site or digital garden using a local asset toolchain (like a GNU `Makefile` paired with Emacs/Pandoc), compilation decisions usually rely on the standard filesystem clock inequality:
Is tsource > ttarget?
In a local development workspace, this works perfectly. However, migrating this architecture to a stateless CI/CD environment (like a GitHub Actions runner) causes the dependency graph to collapse:
Trying to resolve this by blindly wiping directories or forcing updates (`touch notes//*.org`) destroys the performance benefits of incremental compilation, forcing heavy, full-tree rebuilds on every tiny commit.
—
## The Solution: Upstream Ingestion Layer Optimization
Instead of forcing the container's local file system to guess what changed via deceptive clock values, we can leverage the repository's cryptographic commit graph to feed deterministic data down to the compiler.
By increasing the container's ingestion depth to `fetch-depth: 2`, we force Git to pull down the current commit and its immediate structural parent into the local `.git/` metadata store. This grants the runner enough localized history to execute a raw memory-speed `git diff`.
### The Optimized Pipeline Architecture (`.github/workflows/build.yml`)
Instead of running a blind `make all`, the pipeline queries Git for the exact file paths changed in the push, transforms those source paths into the explicit expected target file paths, and passes them straight to `make` as targeted command-line variable overrides.
```yaml
name: Checkout Repository uses: actions/checkout@v4 with: fetch-depth: 2 # Ingests the current commit and its parent
name: Compute Changes and Run Make run: |
CHANGEDORG=$(git diff --name-only HEAD^1 HEAD | grep '^notes/.*\.org$' || true)
if [ -z "$CHANGEDORG" ]; then echo "No note files modified in this push. Skipping compilation." exit 0 fi
MAKETARGETS="" for file in $CHANGEDORG; do if [ -f "$file" ]; then RELPATH=${file#notes/} TARGETMD="public-export/${RELPATH%.org}.md" MAKETARGETS="$MAKETARGETS $TARGETMD" fi done
echo "Executing toolchain for targets: $MAKETARGETS" make $MAKETARGETS
```
—
## Pitfall: Destructive Deployment Synced Deletions
When deploying a sparse, incrementally built directory (`./public-export`) to a deployment target branch (like `gh-pages`), automated deployment handlers (e.g., `peaceiris/actions-gh-pages`) defaults to a destructive synchronization strategy. If a file exists on the remote deployment branch but is absent from the runner's immediate build folder, the action assumes it has been deleted and purges it.
To prevent an incremental build from wiping out the rest of your historical notes from the tracking branch, you must explicitly shift the deployment operation from a destructive override to an in-place accumulation loop:
```yaml
```
## Architectural Takeaway
In systems engineering, patching tools downstream to accommodate poorly structured environments often introduces brittle edge cases. By resolving the issue at the data ingestion layer (`fetch-depth: 2`), the internal compilation engine is spared from making decisions using a broken clock, preserving an elegant, deterministic compilation loop.