docs(runner): Add how-to for bootstrapping a broken runner image #86 #88

Merged

imAsparky merged 2 commits from issue-86 into main

2026-04-25 11:15:19 +00:00

imAsparky commented

2026-04-25 11:06:07 +00:00

Owner

Adds a diataxis-style how-to under docs/ covering the full procedure:
recognising the situation, confirming what's missing, manual rebuild
and push, the read-vs-write token scope trap that catches most people
on the credentials step, verification, and architectural alternatives
for projects that want to break the dependency permanently.

URLs in the guide are specific to the current Forgejo deployment.
A note at the top flags this for future open-source readiness work.

The how-to is a generic version of the recovery work that fixed #82.
Future maintainers should be able to follow it without needing to
reconstruct the procedure from commit history. Bootstrap commands
are copy-paste-and-run for this deployment specifically.
"""

A new how-to guide is available for maintainers: when the CI runner
image is broken and the build workflow cannot rebuild it, follow
docs/how-to-bootstrap-runner-image.md to recover.
"""

Closes #86
Refs #82

When the CI runner image is broken or missing a required tool, the Build Runner Image workflow cannot self-heal because it runs inside that very image -- the classic chicken-and-egg. Recovering requires building and pushing the image manually on the host, plus knowing which Forgejo token scopes the registry actually needs. Adds a diataxis-style how-to under docs/ covering the full procedure: recognising the situation, confirming what's missing, manual rebuild and push, the read-vs-write token scope trap that catches most people on the credentials step, verification, and architectural alternatives for projects that want to break the dependency permanently. URLs in the guide are specific to the current Forgejo deployment. A note at the top flags this for future open-source readiness work. [dev-notes]: """ The how-to is a generic version of the recovery work that fixed #82. Future maintainers should be able to follow it without needing to reconstruct the procedure from commit history. Bootstrap commands are copy-paste-and-run for this deployment specifically. """ [doc-notes]: """ A new how-to guide is available for maintainers: when the CI runner image is broken and the build workflow cannot rebuild it, follow docs/how-to-bootstrap-runner-image.md to recover. """ Closes #86 Refs #82

imAsparky added the

Kind/Documentation

label

2026-04-25 11:06:07 +00:00

imAsparky self-assigned this

2026-04-25 11:06:07 +00:00

imAsparky added 1 commit

2026-04-25 11:06:07 +00:00

docs(runner): Add how-to for bootstrapping a broken runner image #86

Test Python 3.10 Tests passed on Python 3.10

CI / Test Python 3.10 (pull_request) Successful in 59s

Details

Test Python 3.11 Tests passed on Python 3.11

CI / Test Python 3.11 (pull_request) Successful in 57s

Details

Test Python 3.12 Tests passed on Python 3.12

CI / Test Python 3.12 (pull_request) Successful in 58s

Details

Test Python 3.13 Tests passed on Python 3.13

CI / Test Python 3.13 (pull_request) Successful in 1m29s

Details

Test Python 3.14 Tests passed on Python 3.14

CI / Test Python 3.14 (pull_request) Successful in 58s

Details

CI / Lint and Type Check (pull_request) Successful in 40s

Details

CI / Update Changelog (pull_request) Successful in 10s

Details

b551f25b7c

When the CI runner image is broken or missing a required tool, the
Build Runner Image workflow cannot self-heal because it runs inside
that very image -- the classic chicken-and-egg. Recovering requires
building and pushing the image manually on the host, plus knowing
which Forgejo token scopes the registry actually needs.

Adds a diataxis-style how-to under docs/ covering the full procedure:
recognising the situation, confirming what's missing, manual rebuild
and push, the read-vs-write token scope trap that catches most people
on the credentials step, verification, and architectural alternatives
for projects that want to break the dependency permanently.

URLs in the guide are specific to the current Forgejo deployment.
A note at the top flags this for future open-source readiness work.

[dev-notes]:
"""
The how-to is a generic version of the recovery work that fixed #82.
Future maintainers should be able to follow it without needing to
reconstruct the procedure from commit history. Bootstrap commands
are copy-paste-and-run for this deployment specifically.
"""

[doc-notes]:
"""
A new how-to guide is available for maintainers: when the CI runner
image is broken and the build workflow cannot rebuild it, follow
docs/how-to-bootstrap-runner-image.md to recover.
"""

Closes #86
Refs #82

forgejo-actions added 1 commit

2026-04-25 11:12:29 +00:00