docs: fix stale references across all documentation
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 <noreply@anthropic.com>
This commit is contained in:
S
2
PLAN.md
2
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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user