privacy-in-design/gitea-migration
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix stale references across all documentation

Browse Source 
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
2026-03-01 12:55:23 -05:00
parent 6f97f5f08f
commit 045283be50
4 changed files with 88 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
PLAN.md
View File

@@ -304,7 +304,7 @@ gitea-migration/
| `GET /api/v1/admin/runners` | Phase 3 post-check (list runners) | | `GET /api/v1/admin/runners` | Phase 3 post-check (list runners) |
| `POST /api/v1/repos/{owner}/{repo}/push_mirrors` | Phase 6 (create push mirror) | | `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 | | `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 | | `POST /api/v1/repos/{owner}/{repo}/branch_protections` | Phase 7 |
| `GET /api/v1/repos/{owner}/{repo}/branch_protections` | Phase 7 post-check | | `GET /api/v1/repos/{owner}/{repo}/branch_protections` | Phase 7 post-check |
| `DELETE /api/v1/repos/{owner}/{repo}/branch_protections/{name}` | Phase 7 teardown | | `DELETE /api/v1/repos/{owner}/{repo}/branch_protections/{name}` | Phase 7 teardown |

3
README.md
View File

@@ -68,6 +68,7 @@ gitea-migration/
├── lib/common.sh # Shared functions + .env validators ├── lib/common.sh # Shared functions + .env validators
├── setup/ ├── setup/
│ ├── configure_env.sh # Interactive .env wizard (~65 prompts) │ ├── configure_env.sh # Interactive .env wizard (~65 prompts)
│ ├── configure_runners.sh # Interactive runner definition wizard
│ ├── macbook.sh # Local prerequisites (brew packages) │ ├── macbook.sh # Local prerequisites (brew packages)
│ ├── unraid.sh # Remote prerequisites (static binaries) │ ├── unraid.sh # Remote prerequisites (static binaries)
│ ├── fedora.sh # Remote prerequisites (dnf packages) │ ├── fedora.sh # Remote prerequisites (dnf packages)
@@ -89,7 +90,7 @@ gitea-migration/
├── backup/ ├── backup/
│ ├── backup_primary.sh # Gitea dump, SCP to Fedora │ ├── backup_primary.sh # Gitea dump, SCP to Fedora
│ └── restore_to_primary.sh # Restore dump to Unraid │ └── 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 ├── run_all.sh # Full pipeline orchestration
├── teardown_all.sh # Reverse teardown (9 to 1) ├── teardown_all.sh # Reverse teardown (9 to 1)
├── manage_runner.sh # Dynamic runner add/remove/list ├── manage_runner.sh # Dynamic runner add/remove/list

12
USAGE_GUIDE.md
View File

@@ -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) ### 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: **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: Output:
``` ```
NAME HOST LABELS TYPE STATUS NAME HOST LABELS TYPE CAP STATUS
---- ---- ------ ---- ------ ---- ---- ------ ---- --- ------
unraid-runner 192.168.1.10 linux docker online unraid-runner 192.168.1.10 linux docker 2 online
fedora-runner 192.168.1.20 linux docker idle fedora-runner 192.168.1.20 linux docker 2 idle
macbook-runner local macos native online macbook-runner local macos native 1 online
``` ```
### Adding a runner ### Adding a runner

102
contracts/gitea-api.md
View File

@@ -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 ### GET /user
**Used in**: Preflight (validate token), Phase 1 post-check **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 ### POST /repos/{owner}/{repo}/push_mirrors
**Used in**: Phase 6 **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 ### 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 **Purpose**: Get instance API settings
**Response** (200): Settings object with `has_actions` field **Response** (200): Settings object with `has_actions` field
@@ -517,6 +527,52 @@ Auth: `Authorization: token ${GITHUB_TOKEN}`
**Response** (204): No Content **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 ## Error Responses