Document that git-pages sites need manual removal — deleting the repo does not unpublish them #89

New issue

Open

opened 2026-07-30 02:35:15 +00:00 by gravityfargo · 0 comments

gravityfargo commented

2026-07-30 02:35:15 +00:00

Owner

Anyone publishing docs through the git-pages workflow needs to know this, and nothing currently says it.

The behaviour

Deleting a repo does not unpublish its site. git-pages holds the uploaded archive independently of the repo, so the page stays live afterwards with no owner and no obvious way to retract it.

Measured on 2026-07-29 against a throwaway repo:

gravityfargo/test-docs-pdoc was deleted; the API 404s it.
https://gravityfargo.modernleft.page/test-docs-pdoc/test_docs_pdoc.html still returned 200 with the full 33601-byte page.
Response carried server: git-pages (5235f43d5328) with cache-control: max-age=60 already expired, so it was the origin answering, not a cache.

Only checked minutes after deletion, so a longer-cycle reaper is not ruled out — but nothing observed suggests one.

That orphan is still live and is a real example rather than a hypothetical.

Why it bites

Deletion also removes the workflow and the forgejo.token it used to upload. Those are the only things that could overwrite the site. So the order is not recoverable: once the repo is gone, the publisher has lost every mechanism they had to change what is served.

This matters most for a private repo, because git-pages serves the archive unauthenticated regardless of repo visibility. Deleting a private repo can therefore leave its docs permanently public.

What to document

In whichever page covers publishing docs:

Deleting a repo leaves its published site serving. Retract before deleting, never after.
Removing an already-orphaned site requires manual intervention on the git-pages host (server-montreal/docker-compose/git-pages); there is no self-service path through the forge.
A private repo publishes a public site, so treat adopting the docs workflow as making the docs public.

One gap worth naming rather than papering over: whether an empty deploy actually clears a published site is untested. If it does, that is the clean retraction step and belongs in the docs as such. If it does not, manual host cleanup is the only route even for a repo you still control. Worth confirming before the wording is finalised.

Context: found while validating the docs-publish catalog entry in the templates repo, which now records the same finding in its VALIDATION.md.

Anyone publishing docs through the git-pages workflow needs to know this, and nothing currently says it. ## The behaviour Deleting a repo does not unpublish its site. git-pages holds the uploaded archive independently of the repo, so the page stays live afterwards with no owner and no obvious way to retract it. Measured on 2026-07-29 against a throwaway repo: - `gravityfargo/test-docs-pdoc` was deleted; the API 404s it. - `https://gravityfargo.modernleft.page/test-docs-pdoc/test_docs_pdoc.html` still returned 200 with the full 33601-byte page. - Response carried `server: git-pages (5235f43d5328)` with `cache-control: max-age=60` already expired, so it was the origin answering, not a cache. Only checked minutes after deletion, so a longer-cycle reaper is not ruled out — but nothing observed suggests one. That orphan is still live and is a real example rather than a hypothetical. ## Why it bites Deletion also removes the workflow and the `forgejo.token` it used to upload. Those are the only things that could overwrite the site. So the order is not recoverable: once the repo is gone, the publisher has lost every mechanism they had to change what is served. This matters most for a **private** repo, because git-pages serves the archive unauthenticated regardless of repo visibility. Deleting a private repo can therefore leave its docs permanently public. ## What to document In whichever page covers publishing docs: - Deleting a repo leaves its published site serving. Retract before deleting, never after. - Removing an already-orphaned site requires manual intervention on the git-pages host (`server-montreal/docker-compose/git-pages`); there is no self-service path through the forge. - A private repo publishes a public site, so treat adopting the docs workflow as making the docs public. One gap worth naming rather than papering over: whether an empty deploy actually clears a published site is **untested**. If it does, that is the clean retraction step and belongs in the docs as such. If it does not, manual host cleanup is the only route even for a repo you still control. Worth confirming before the wording is finalised. Context: found while validating the `docs-publish` catalog entry in the templates repo, which now records the same finding in its `VALIDATION.md`.

No labels

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

ModernLeft/modernleft-docs#89

No description provided.

Rows
Columns