ai github actions problem

References

Summary

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:

  1. Shallow Clone Default: By default, actions optimize for network speed by executing a shallow clone (`fetch-depth: 1`), pulling down only the single tip commit snapshot.
  2. Clock Equalization: Because the runner begins with a completely empty disk, the checkout action streams and materializes all source files (`.org`) and tracked target files (`.html` / `.md`) sequentially within milliseconds.
  3. The Result: Every file lands on the runner disk with an identical checkout timestamp. When `make` checks the clock, tsource is not strictly greater than ttarget. The compilation engine assumes no modifications have occurred, outputting a false-positive `No need to remake target` and skipping the build completely.

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

```

—

## 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.