Adds two new docs and a banner on the existing GitHub-runner doc.
WHY: the user already has Gitea Actions configured across all 20+
repos (.gitea/workflows/ci.yml). Building a parallel GitHub Actions
self-hosted runner pipeline is unnecessary work that also drags in
GitHub Organization migration pressure (with Vercel/Netlify pricing
side-effects on free tiers).
The canonical architecture instead:
- Each Gitea instance (corp Mac local + Hostinger VM) runs its own
act_runner.
- A single publish-packages.yml workflow lives in every package-
publishing repo.
- When the same git tag is pushed to both Giteas, each one builds
inside the same pinned Docker image (node:20-bookworm@sha256:...)
with the same lockfile, producing BYTE-IDENTICAL tarballs.
- No sync script is needed; the shared git tag IS the sync mechanism.
- Lockfile integrity hashes match across both registries, so corp Mac
and personal Mac + Hostinger prod all see the same packages.
New: HOSTINGER_GITEA_ACT_RUNNER_SETUP.md
- Codex-actionable prompt to install act_runner on the Hostinger VM
- Pre-flight checks (arch detection, Docker daemon, Gitea reachable)
- Idempotent user creation, SHA-verified binary download
- Docker mode runner config with labels mapping ubuntu-latest to
pinned Node image
- Smoke test + full E2E with throwaway @bytelyst/_runner-e2e-test
package
- The architectural invariant check: cross-Gitea SHA comparison —
same tag pushed to both must produce identical tarballs
- Monitoring (Gitea UI, API, systemd journal)
- Hardening, rollback, deliverables, guardrails, questions
New: GITEA_PACKAGES_PUBLISH_WORKFLOW.md
- The actual publish-packages.yml triggered by v* tags
- Docker image pinned by digest for build determinism
- pnpm@9.12.0 pinned, --frozen-lockfile, host-network container
- Token mounted as read-only secret file (not env var)
- Concurrency cancel-in-progress: false (never cancel a publish)
- Pack tarballs + SHA512 manifest as Gitea Release assets for audit
trail
- Two propagation strategies: reusable workflow (preferred) vs
sync-publish-workflow.sh script
- Operator runbook for cutting a release
- Failure-mode table + remediation
- Deliverables checklist
Updated: HOSTINGER_GITHUB_RUNNER_SETUP.md
- Added 'PLAN B' banner at the top
- Cross-links to the Gitea Actions docs
- Kept the doc intact as a valid alternative if priorities ever
shift to making GitHub Actions the publish driver
Adds the missing pieces revealed during review:
§1 Multi-repo registration decision — choose repo-level vs org-level
up-front. Default doc remains repo-level, but explicitly calls out
org-level as the scaling path for 20+ repos.
§2 Pre-flight check additions:
- Arch detection (x86_64 / aarch64) before downloading runner tarball
- github.com + objects.githubusercontent.com reachability check
- gh CLI auth status check (must be saravanakumardb1)
§4 Installation hardening:
- Step 1 is now idempotent (getent guards on useradd/usermod)
- Step 3 queries latest runner version via gh api (no more stale pin)
- Step 3 includes SHA256 verification of the downloaded tarball
against the release-notes manifest, with explicit STOP-if-mismatch
- Step 3 has REGISTRATION_URL var with commented Option A/B for
repo-level vs org-level scope
§5 Smoke test — added explicit git checkout/add/commit/push commands
for creating the runner/smoke branch (was implicit before).
§8 (renamed) — comprehensive org migration guide:
- Side-by-side table: personal account today vs under-an-org
- Bash loop to transfer all 18 repos via gh api
- git remote set-url commands for each local clone
- Post-migration org-level registration token fetch
- Workflow propagation strategies (reusable workflow vs sync script)
§9 (new) — Monitoring + observability:
- GitHub Actions tab per-repo + per-org workflow views
- Runner pool health (Settings → Actions → Runners) at repo + org level
- gh CLI commands for scripted monitoring (run watch, list, view, runners)
- Host-side journalctl + _diag/ inspection commands
§14 Questions — updated to ask about scope (repo vs org) first.
Section numbering shifted by +1 from §9 onward to make room for the
new Monitoring section.
Delegation prompt for the Codex agent running on the Hostinger VM to:
- Install a dedicated GitHub Actions self-hosted runner under gha-runner user
- Register it with saravanakumardb1/learning_ai_common_plat
- Run as a systemd service with auto-start
- Install Node 20 / pnpm 9 / gh CLI / Docker prerequisites
- Wire up local Gitea publish token
Includes full end-to-end validation that proves the actual publish
pipeline works:
- Creates a throwaway @bytelyst/_runner-e2e-test package
- Publishes to local Gitea
- Uploads tarball as GitHub Release asset
- Verifies Gitea registry returns the version
- Verifies pnpm install + require works from a clean directory
- Verifies the byte-identical-tarball invariant (sha256 match between
Gitea-served tarball and GitHub Release asset) — this is the key
guarantee that lockfiles will remain portable across corp Mac's
local Gitea after sync
- Documents cleanup of test artifacts
Plus pre-flight checks, hardening (systemd limits, log rotation,
workflow approval), scaling notes, deliverables checklist, guardrails,
rollback, and follow-up prompt list (publish-packages.yml,
bytelyst-sync script, SKILL doc).
