Remove Obsolete Assets Safely During Article Revisions

Retiring old content during article updates can leave behind unwanted media files. A crucial step is confirming the previous revision ID before removing any paths. Assuming that deleting files by name alone is unsafe, as it risks broken references or accidental data loss. As teams continually update technical guides, old screenshots, diagrams, and hero images accumulate unnecessarily in storage directories, leading to repository bloat and slower continuous integration pipelines.

To mitigate this, a structured retirement protocol is necessary, requiring programmatic validation that links each file to its exact source revision. The publishing pipeline should first locate the nearest earlier published vault revision for the same draft filename, rather than scanning broad repositories which can match unrelated files from different authors or sections.

Anchoring the search to the specific content directory and verifying the canonical filename stem ensures the script only inspects the true predecessor of the current piece. In complex editorial workflows, special cases like drafts in a budget-safe state need isolation from live asset trees until formal promotion. If no prior published record exists, the promotion script skips asset collection entirely to avoid runtime errors on initial publications.

Before collecting old asset identifiers, the code verifies three properties from the historical record: article ID, URL slug consistency, and the previous record being explicitly marked as published. Failing any of these checks aborts the asset cleanup routine while allowing the new revision to publish normally, preventing accidental media deletion during concurrent updates.

Automated systems often face race conditions when multiple authors edit related files at once. Checking explicit IDs instead of just file modification timestamps avoids ambiguity. If an article slug changes due to restructuring, the validation layer detects it and requires explicit confirmation before proceeding with file removals to prevent accidental deletion when content is reorganized.

After identifying previous assets, the pipeline compares them to the incoming revision asset list, retaining referenced paths while flagging unreferenced ones for removal. Instead of issuing individual delete requests, the publishing worker packages the article update and obsolete paths into a single tree creation payload using the GitHub REST API Git Trees endpoint.

Committing these changes atomically guarantees repository consistency throughout deployment, eliminating the vulnerability of broken links or missing images due to partial network failures. If tree creation fails, the transaction rolls back cleanly on the remote server, ensuring readers never see broken content from premature deletions.

Edge cases like multiple language versions require the asset comparison to include locale directories to avoid cross-language asset corruption. Network timeouts during large payload submissions can cause rate-limit errors or gateway timeouts in GitHub API commits. Implementing exponential backoff retries for the tree creation request prevents transient network issues from aborting valid publication runs.

The verification checklist confirms that the previous published record matches the article ID and slug, ensures unreferenced assets are correctly flagged for deletion, tests identity mismatch scenarios to ensure cleanup aborts when needed, and verifies that the final GitHub tree commit updates the article content and removes obsolete assets simultaneously.