gitea-migration/contracts/gitea-api.md

# API Contracts — Gitea Migration Toolkit

All API calls used by the migration scripts. Every `gitea_api`, `gitea_backup_api`, and `github_api` call in the codebase MUST have a corresponding entry here.

---

## Gitea REST API v1

Base URL: `${GITEA_INTERNAL_URL}/api/v1` (primary) or `${GITEA_BACKUP_INTERNAL_URL}/api/v1` (backup)
Auth: `Authorization: token ${GITEA_ADMIN_TOKEN}` (or `GITEA_BACKUP_ADMIN_TOKEN`)

---

### POST /users/{username}/tokens

**Used in**: Phase 1 (primary), Phase 2 (backup)
**Purpose**: Generate API token for admin user
**Auth**: Basic auth (`-u username:password`) — token doesn't exist yet

**Request**:
```json
{
  "name": "string",
  "scopes": ["all"]
}
```

**Response** (201):
```json
{
  "id": 1,
  "name": "migration-token",
  "sha1": "abc123...",
  "token_last_eight": "abc12345"
}
```

**Notes**: `sha1` field contains the full token value — save this immediately, it's only returned once.

---

### GET /user

**Used in**: Preflight (validate token), Phase 1 post-check
**Purpose**: Verify the current authenticated user

**Request**: No body

**Response** (200):
```json
{
  "id": 1,
  "login": "string",
  "email": "string",
  "is_admin": true
}
```

---

### POST /orgs

**Used in**: Phase 1
**Purpose**: Create organization

**Request**:
```json
{
  "username": "string",
  "full_name": "string",
  "description": "string",
  "visibility": "public"
}
```

**Response** (201):
```json
{
  "id": 1,
  "name": "string",
  "full_name": "string",
  "visibility": "public"
}
```

---

### GET /orgs/{org}

**Used in**: Phase 1 (idempotency check), Phase 1 post-check
**Purpose**: Check if organization exists

**Request**: No body

**Response** (200):
```json
{
  "id": 1,
  "name": "string",
  "full_name": "string"
}
```

**404**: Organization does not exist

---

### POST /repos/migrate

**Used in**: Phase 4 (import from GitHub), Phase 4 (Fedora pull mirrors)
**Purpose**: Migrate/mirror a repository from an external source

**Request (GitHub import — primary)**:
```json
{
  "clone_addr": "https://github.com/{owner}/{repo}.git",
  "auth_token": "string (GitHub PAT)",
  "repo_owner": "string (Gitea org name)",
  "repo_name": "string",
  "service": "github",
  "mirror": false,
  "issues": true,
  "labels": true,
  "milestones": false,
  "wiki": false
}
```

**Request (Fedora pull mirror)**:
```json
{
  "clone_addr": "http://{UNRAID_IP}:{PORT}/{org}/{repo}.git",
  "auth_username": "string",
  "auth_password": "string",
  "repo_owner": "string (admin username on Fedora)",
  "repo_name": "string",
  "mirror": true,
  "mirror_interval": "8h"
}
```

**Response** (201):
```json
{
  "id": 1,
  "name": "string",
  "full_name": "org/repo",
  "empty": false,
  "mirror": false,
  "default_branch": "main"
}
```

**Notes**: Migration is async — poll `GET /repos/{owner}/{repo}` until `empty` is `false`.

---

### GET /repos/{owner}/{repo}

**Used in**: Phase 4 (idempotency + polling), Phase 4 post-check, Phase 5 post-check
**Purpose**: Get repository details

**Request**: No body

**Response** (200):
```json
{
  "id": 1,
  "name": "string",
  "full_name": "org/repo",
  "empty": false,
  "mirror": false,
  "default_branch": "main",
  "archived": false,
  "description": "string"
}
```

**404**: Repository does not exist

---

### DELETE /repos/{owner}/{repo}

**Used in**: Phase 4 teardown
**Purpose**: Delete a repository

**Request**: No body
**Response**: 204 No Content

---

### GET /repos/{owner}/{repo}/commits

**Used in**: Phase 4 post-check
**Purpose**: Verify repo has commits

**Query params**: `?limit=1`

**Response** (200): Array of commit objects (at least 1 if repo has content)

---

### GET /repos/{owner}/{repo}/contents/{filepath}

**Used in**: Phase 5 post-check (check `.gitea/workflows/` exists), Phase 9 (check security workflow exists)
**Purpose**: Get file or directory contents

**Response** (200): File/directory metadata
**404**: Path does not exist

---

### GET /admin/runners/registration-token

**Used in**: Phase 3
**Purpose**: Get registration token for new runners

**Request**: No body

**Response** (200):
```json
{
  "token": "string"
}
```

**Notes**: Requires admin-level API token.

---

### GET /admin/runners

**Used in**: Phase 3 post-check
**Purpose**: List all registered runners

**Request**: No body

**Response** (200):
```json
[
  {
    "id": 1,
    "name": "string",
    "status": "online",
    "labels": ["linux"]
  }
]
```

---

### POST /repos/{owner}/{repo}/push_mirrors

**Used in**: Phase 6
**Purpose**: Create a push mirror to GitHub

**Request**:
```json
{
  "remote_address": "https://github.com/{owner}/{repo}.git",
  "remote_username": "string",
  "remote_password": "string (GitHub PAT)",
  "interval": "8h",
  "sync_on_commit": true
}
```

**Response** (201):
```json
{
  "id": 1,
  "remote_name": "string",
  "remote_address": "string",
  "interval": "8h",
  "sync_on_commit": true
}
```

---

### GET /repos/{owner}/{repo}/push_mirrors

**Used in**: Phase 6 (idempotency check), Phase 6 post-check
**Purpose**: List push mirrors for a repo

**Response** (200): Array of push mirror objects

---

### DELETE /repos/{owner}/{repo}/push_mirrors/{id}

**Used in**: Phase 6 teardown
**Purpose**: Remove a push mirror

**Response**: 204 No Content

---

### POST /repos/{owner}/{repo}/push_mirrors-sync

**Used in**: Phase 6 post-check
**Purpose**: Trigger immediate push mirror sync

**Request**: No body
**Response**: 200 OK

---

### POST /repos/{owner}/{repo}/branch_protections

**Used in**: Phase 7, Phase 9 (update with status checks)
**Purpose**: Create branch protection rule

**Request**:
```json
{
  "branch_name": "main",
  "enable_push": false,
  "enable_push_whitelist": false,
  "require_signed_commits": false,
  "enable_status_check": true,
  "status_check_contexts": [],
  "enable_approvals_whitelist": false,
  "required_approvals": 1
}
```

**Response** (201): Branch protection object

---

### GET /repos/{owner}/{repo}/branch_protections

**Used in**: Phase 7 (idempotency), Phase 7 post-check
**Purpose**: List all branch protection rules

**Response** (200): Array of branch protection objects

---

### GET /repos/{owner}/{repo}/branch_protections/{name}

**Used in**: Phase 7 (check specific branch)
**Purpose**: Get a specific branch protection rule

**Response** (200): Branch protection object
**404**: Rule does not exist

---

### PATCH /repos/{owner}/{repo}/branch_protections/{name}

**Used in**: Phase 9 (add status check contexts)
**Purpose**: Update branch protection rule

**Request** (partial update):
```json
{
  "enable_status_check": true,
  "status_check_contexts": ["semgrep", "trivy", "gitleaks"]
}
```

**Response** (200): Updated branch protection object

---

### DELETE /repos/{owner}/{repo}/branch_protections/{name}

**Used in**: Phase 7 teardown, Phase 9 teardown
**Purpose**: Delete branch protection rule

**Response**: 204 No Content

---

### 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)
**Purpose**: Get instance API settings

**Response** (200): Settings object with `has_actions` field

---

## GitHub REST API

Base URL: `https://api.github.com`
Auth: `Authorization: token ${GITHUB_TOKEN}`

---

### GET /user

**Used in**: Preflight
**Purpose**: Validate GitHub personal access token

**Request**: No body

**Response** (200):
```json
{
  "login": "string",
  "id": 1
}
```

**401**: Token invalid or expired

---

### GET /repos/{owner}/{repo}

**Used in**: Preflight (verify repos exist), Phase 8 (check archive status)
**Purpose**: Get repository details

**Response** (200):
```json
{
  "name": "string",
  "full_name": "owner/repo",
  "archived": false,
  "description": "string"
}
```

**404**: Repository does not exist

---

### PATCH /repos/{owner}/{repo}

**Used in**: Phase 8 (archive repos + update description), Phase 8 teardown (un-archive)
**Purpose**: Update repository settings

**Request (archive)**:
```json
{
  "archived": true,
  "description": "[MOVED] Now at https://git.domain.com/org/repo — was: original description"
}
```

**Request (un-archive)**:
```json
{
  "archived": false
}
```

**Response** (200): Updated repository object