From 045283be504fe0cc800062fb579703f43b0f268b Mon Sep 17 00:00:00 2001 From: S Date: Sun, 1 Mar 2026 12:55:23 -0500 Subject: [PATCH] docs: fix stale references across all documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: add missing configure_runners.sh, fix check count 22→24 USAGE_GUIDE.md: fix check refs 23-24→21-22, add CAP column to manage_runner list example PLAN.md: fix mirror-sync→push_mirrors-sync endpoint contracts/gitea-api.md: add 5 missing endpoints (DELETE tokens, repo-scoped runner registration, PUT/POST GitHub Pages, GitHub commits), remove unused actions/workflows endpoint, fix GET /settings/api Used-in to include Phase 2 Co-Authored-By: Claude Opus 4.6 --- PLAN.md | 2 +- README.md | 3 +- USAGE_GUIDE.md | 12 ++--- contracts/gitea-api.md | 102 +++++++++++++++++++++++++++++++---------- 4 files changed, 88 insertions(+), 31 deletions(-) diff --git a/PLAN.md b/PLAN.md index 45fe695..c1e33b0 100644 --- a/PLAN.md +++ b/PLAN.md @@ -304,7 +304,7 @@ gitea-migration/ | `GET /api/v1/admin/runners` | Phase 3 post-check (list runners) | | `POST /api/v1/repos/{owner}/{repo}/push_mirrors` | Phase 6 (create push mirror) | | `GET /api/v1/repos/{owner}/{repo}/push_mirrors` | Phase 6 post-check | -| `POST /api/v1/repos/{owner}/{repo}/mirror-sync` | Phase 6 post-check (trigger sync) | +| `POST /api/v1/repos/{owner}/{repo}/push_mirrors-sync` | Phase 6 post-check (trigger sync) | | `POST /api/v1/repos/{owner}/{repo}/branch_protections` | Phase 7 | | `GET /api/v1/repos/{owner}/{repo}/branch_protections` | Phase 7 post-check | | `DELETE /api/v1/repos/{owner}/{repo}/branch_protections/{name}` | Phase 7 teardown | diff --git a/README.md b/README.md index 4d8a83e..e2dac22 100644 --- a/README.md +++ b/README.md @@ -68,6 +68,7 @@ gitea-migration/ ├── lib/common.sh # Shared functions + .env validators ├── setup/ │ ├── configure_env.sh # Interactive .env wizard (~65 prompts) +│ ├── configure_runners.sh # Interactive runner definition wizard │ ├── macbook.sh # Local prerequisites (brew packages) │ ├── unraid.sh # Remote prerequisites (static binaries) │ ├── fedora.sh # Remote prerequisites (dnf packages) @@ -89,7 +90,7 @@ gitea-migration/ ├── backup/ │ ├── backup_primary.sh # Gitea dump, SCP to Fedora │ └── restore_to_primary.sh # Restore dump to Unraid -├── preflight.sh # 22 pre-flight validation checks +├── preflight.sh # 24 pre-flight validation checks ├── run_all.sh # Full pipeline orchestration ├── teardown_all.sh # Reverse teardown (9 to 1) ├── manage_runner.sh # Dynamic runner add/remove/list diff --git a/USAGE_GUIDE.md b/USAGE_GUIDE.md index 53392b9..2861ec7 100644 --- a/USAGE_GUIDE.md +++ b/USAGE_GUIDE.md @@ -254,7 +254,7 @@ If this fails, add your public key to the remote host's `~/.ssh/authorized_keys` ### Cross-host SSH fails (Unraid cannot reach Fedora or vice versa) -**Symptom**: Preflight checks 23-24 fail, or `backup/backup_primary.sh` fails on the SCP step. +**Symptom**: Preflight checks 21-22 fail, or `backup/backup_primary.sh` fails on the SCP step. **Fix**: Run the cross-host SSH setup: @@ -603,11 +603,11 @@ The script uses `.env.example` as a template to preserve section headers and com Output: ``` -NAME HOST LABELS TYPE STATUS ----- ---- ------ ---- ------ -unraid-runner 192.168.1.10 linux docker online -fedora-runner 192.168.1.20 linux docker idle -macbook-runner local macos native online +NAME HOST LABELS TYPE CAP STATUS +---- ---- ------ ---- --- ------ +unraid-runner 192.168.1.10 linux docker 2 online +fedora-runner 192.168.1.20 linux docker 2 idle +macbook-runner local macos native 1 online ``` ### Adding a runner diff --git a/contracts/gitea-api.md b/contracts/gitea-api.md index c537242..a1f3ee2 100644 --- a/contracts/gitea-api.md +++ b/contracts/gitea-api.md @@ -39,6 +39,20 @@ Auth: `Authorization: token ${GITEA_ADMIN_TOKEN}` (or `GITEA_BACKUP_ADMIN_TOKEN` --- +### DELETE /users/{username}/tokens/{token_name} + +**Used in**: Phase 1, Phase 2 (idempotent re-run safety) +**Purpose**: Delete a stale API token before regenerating +**Auth**: Basic auth (`-u username:password`) + +**Request**: No body +**Response**: 204 No Content +**404**: Token does not exist (safe to ignore) + +**Notes**: Gitea returns 409 Conflict if you try to POST a token with a name that already exists. Deleting first makes token generation idempotent. + +--- + ### GET /user **Used in**: Preflight (validate token), Phase 1 post-check @@ -250,6 +264,24 @@ Auth: `Authorization: token ${GITEA_ADMIN_TOKEN}` (or `GITEA_BACKUP_ADMIN_TOKEN` --- +### GET /repos/{owner}/{repo}/actions/runners/registration-token + +**Used in**: `manage_runner.sh` (repo-scoped runner registration) +**Purpose**: Get registration token scoped to a specific repo (vs admin-level global token) + +**Request**: No body + +**Response** (200): +```json +{ + "token": "string" +} +``` + +**Notes**: Used when `repos` field in `runners.conf` is set to a specific repo name instead of `all`. Requires write access to the repo. + +--- + ### POST /repos/{owner}/{repo}/push_mirrors **Used in**: Phase 6 @@ -375,31 +407,9 @@ Auth: `Authorization: token ${GITEA_ADMIN_TOKEN}` (or `GITEA_BACKUP_ADMIN_TOKEN` --- -### GET /repos/{owner}/{repo}/actions/workflows - -**Used in**: Phase 5 post-check -**Purpose**: List workflows in repo - -**Response** (200): -```json -{ - "total_count": 1, - "workflows": [ - { - "id": "string", - "name": "string", - "path": ".gitea/workflows/ci.yml", - "state": "active" - } - ] -} -``` - ---- - ### GET /settings/api -**Used in**: Phase 1 post-check (verify Actions enabled) +**Used in**: Phase 1 post-check, Phase 2 post-check (verify Actions enabled) **Purpose**: Get instance API settings **Response** (200): Settings object with `has_actions` field @@ -517,6 +527,52 @@ Auth: `Authorization: token ${GITHUB_TOKEN}` **Response** (204): No Content +### PUT /repos/{owner}/{repo}/pages + +**Used in**: Phase 8 teardown (restore Pages configuration) +**Purpose**: Update GitHub Pages configuration + +**Request**: +```json +{ + "cname": "string", + "source": { + "branch": "main", + "path": "/" + } +} +``` + +**Response** (204): No Content + +### POST /repos/{owner}/{repo}/pages + +**Used in**: Phase 8 teardown (re-enable Pages if it was deleted) +**Purpose**: Create/enable GitHub Pages configuration + +**Request**: +```json +{ + "source": { + "branch": "main", + "path": "/" + } +} +``` + +**Response** (201): Pages configuration object + +### GET /repos/{owner}/{repo}/commits + +**Used in**: Phase 6 post-check (compare Gitea and GitHub HEAD SHAs after mirror sync) +**Purpose**: Get recent commits (GitHub side) + +**Query params**: `?per_page=1` + +**Response** (200): Array of commit objects + +**Notes**: The Gitea version of this endpoint is documented above. This GitHub-side usage verifies that push mirror sync propagated the latest commit. + --- ## Error Responses