Remove Obsolete Assets Safely During Article Revisions

Revising a published article leaves orphaned media files behind.

Quick solution: Validate the prior revision ID before subtracting active paths.

if (p.id !== r.id) throw new Error();

Deleting files by slug or filename alone is risky when the automation has not proved that the old files belong to the exact same published piece, which can lead to broken references, orphan files, or accidental data loss in production repositories. When teams update technical guides, old screenshots, diagrams, and hero images accumulate rapidly in storage directories. Without a structured retirement protocol, repositories bloat with unused binaries, and continuous integration pipelines take longer to clone and scan. Managing these assets requires programmatic validation steps that connect each file to its exact source revision.

Resolving the Previous Article Record

The publishing pipeline must locate the nearest earlier published vault revision for the same draft filename stem rather than executing a broad repository search across the entire project. Searching broadly across unrelated directories increases the chance of matching similarly named files from different authors or separate content folders. By anchoring the search to the specific content directory and verifying the canonical filename stem, the script ensures it inspects only the true predecessor of the current piece.

When managing complex editorial workflows, teams often need to handle edge cases such as Deferring Publication After A Budget Safe drafts, where temporary states must remain isolated from live asset trees until formal promotion occurs. If no previous published record exists, the promotion script skips the asset collection phase entirely and writes only the new revision files, preventing runtime errors on initial publications. Establishing this boundary protects draft media from premature deletion while ensuring that active updates clean up after themselves reliably.

Validating Article Identity and State

Before collecting old asset identifiers for removal, the code checks three distinct properties from the historical record. It confirms that the article ID matches, the URL slug remains consistent, and the previous record is explicitly marked as published. If any of these checks fail, the pipeline aborts the asset cleanup routine while still allowing the new article revision to publish normally. This fail-safe behavior prevents a malformed history or an accidental path collision from wiping out media files belonging to a different article during concurrent updates.

Automated systems frequently encounter race conditions when multiple authors update related files simultaneously. Checking explicit IDs rather than relying solely on file modification timestamps eliminates ambiguity. If an article slug changes due to a restructuring effort, the validation layer detects the shift and requires explicit confirmation before proceeding with any file removals. This prevents accidental deletion when content is reorganized into new folder hierarchies.

Subtracting Active References and Executing Atomic Trees

Once the previous assets are identified, the pipeline compares them against the incoming revision asset list. Any path still referenced by the new revision is retained, while unreferenced paths are flagged for removal. Rather than issuing individual delete requests that could leave the site in a partially updated state, the publishing worker packages the article update and the obsolete paths into a single tree creation payload using the GitHub REST API Git Trees endpoint. Committing these changes in one atomic tree update guarantees that the repository state remains consistent throughout the deployment.

Atomic tree updates eliminate the window of vulnerability where a broken link or missing image could be served to readers due to a partial network failure. If the tree creation payload fails, the entire transaction rolls back cleanly on the remote server. This approach ensures that readers never encounter a broken page where a superseded asset was deleted before its replacement finished publishing.

Handling Edge Cases and Failure Modes

Production publishing environments must handle various edge cases gracefully. When an article is translated into multiple languages, each localized version maintains its own asset set. A global cleanup script that ignores language directories might inadvertently delete Spanish hero images while publishing an English revision. Scoping the asset comparison to both the article identifier and the locale directory prevents cross-language asset corruption.

Another common failure mode involves network timeouts during large payload submissions. When committing trees with dozens of high-resolution images, the GitHub API may occasionally return rate-limit errors or gateway timeouts. Implementing exponential backoff retries specifically for the tree creation request prevents transient network hiccups from aborting otherwise valid publication runs.

Verification and Execution Checklist

1. Verify that the previous published record shares the identical article ID and slug before running cleanup.
2. Confirm that unreferenced assets from the prior revision are successfully added to the deletion manifest.
3. Test an identity mismatch scenario to ensure the pipeline aborts cleanup while still publishing the new article revision.
4. Check that the final GitHub tree commit updates the article content and removes the obsolete assets simultaneously.