gitea-migration/PLAN.md

Gitea Migration Toolkit — Implementation Plan

Context

Migrating 3 GitHub repos to self-hosted Gitea (Unraid primary, Fedora backup mirror, GitHub as push mirror). All automation runs from MacBook, SSHing into remote machines. Scripts must be idempotent, .env-driven, with preflight + post-checks + teardown per phase.

---

Architecture Decisions

Decision	Choice	Rationale
Execution model	All scripts run from MacBook, SSH into remotes	Single control plane, no agent installs needed
Gitea deployment	Docker Compose on both Unraid + Fedora	Scriptable, reproducible, version-pinned
Runner deployment (Linux)	Docker container via docker-compose	Consistent with Gitea deployment
Runner deployment (macOS)	Native binary + launchd plist	Docker Desktop on Mac is heavyweight; native binary is lighter and more reliable
Idempotency pattern	Check-before-act (query state, skip if already done)	Every create operation first checks if the resource exists
Template rendering	.tpl files + envsubst	Keeps config templates separate from script logic
Error handling	set -euo pipefail + trap cleanup	Fail fast, no silent errors
API interaction	Shared gitea_api() curl wrapper with JSON/jq	Consistent auth, error checking, response parsing
HTTPS proxy	Nginx config template + Certbot (Docker)	Plain Nginx already on Unraid as Docker container — just add a server block + SSL cert

---

File Structure

gitea-migration/
├── .env.example
├── .env
├── runners.conf.example
├── runners.conf
├── PLAN.md
├── lib/
│   └── common.sh
├── setup/
│   ├── configure_env.sh
│   ├── macbook.sh
│   ├── unraid.sh
│   └── fedora.sh
├── templates/
│   ├── docker-compose-gitea.yml.tpl
│   ├── docker-compose-runner.yml.tpl
│   ├── app.ini.tpl
│   ├── runner-config.yaml.tpl
│   ├── com.gitea.runner.plist.tpl
│   ├── nginx-gitea.conf.tpl
│   └── workflows/
│       └── security-scan.yml.tpl
├── backup/
│   ├── backup_primary.sh
│   └── restore_to_primary.sh
├── contracts/
│   └── gitea-api.md
├── preflight.sh
├── phase1_gitea_unraid.sh
├── phase1_post_check.sh
├── phase1_teardown.sh
├── phase2_gitea_fedora.sh
├── phase2_post_check.sh
├── phase2_teardown.sh
├── phase3_runners.sh
├── phase3_post_check.sh
├── phase3_teardown.sh
├── phase4_migrate_repos.sh
├── phase4_post_check.sh
├── phase4_teardown.sh
├── phase5_migrate_pipelines.sh
├── phase5_post_check.sh
├── phase5_teardown.sh
├── phase6_github_mirrors.sh
├── phase6_post_check.sh
├── phase6_teardown.sh
├── phase7_branch_protection.sh
├── phase7_post_check.sh
├── phase7_teardown.sh
├── phase8_cutover.sh
├── phase8_post_check.sh
├── phase8_teardown.sh
├── phase9_security.sh
├── phase9_post_check.sh
├── phase9_teardown.sh
├── manage_runner.sh
├── run_all.sh
└── teardown_all.sh

---

Implementation Tracker

1. Foundation

#	File	Description	Status
1.1	lib/common.sh	Shared functions: logging, SSH, API wrappers, template rendering, checks	TODO
1.2	.env.example	Add SSL_MODE, SSL_CERT_PATH, SSL_KEY_PATH vars to Nginx section	TODO
1.3	contracts/gitea-api.md	Gitea REST API endpoints used across all phases	TODO

2. Templates

#	File	Description	Status
2.1	templates/docker-compose-gitea.yml.tpl	Gitea + SQLite docker-compose	TODO
2.2	templates/app.ini.tpl	Gitea custom config (INSTALL_LOCK, Actions enabled, etc.)	TODO
2.3	templates/docker-compose-runner.yml.tpl	act_runner docker-compose (Linux)	TODO
2.4	templates/runner-config.yaml.tpl	act_runner config	TODO
2.5	templates/com.gitea.runner.plist.tpl	macOS launchd service for act_runner	TODO
2.6	templates/nginx-gitea.conf.tpl	Nginx reverse proxy server block	TODO
2.7	templates/workflows/security-scan.yml.tpl	Semgrep + Trivy + Gitleaks workflow	TODO

3. Machine Setup

#	File	Description	Status
3.1	setup/configure_env.sh	Interactive wizard: prompts for each .env var, writes to .env	TODO
3.2	setup/macbook.sh	Homebrew, jq, curl, envsubst, git, Xcode CLI Tools, shellcheck, gh	TODO
3.3	setup/unraid.sh	Verify Docker, install docker-compose + jq (static binary)	TODO
3.4	setup/fedora.sh	Install Docker CE, compose plugin, jq, enable systemd services	TODO

4. Preflight

#	File	Description	Status
4.1	preflight.sh	Validate .env, SSH, Docker, ports, DNS, GitHub token, Nginx, repos	TODO

5. Phase 1 — Gitea on Unraid

#	File	Description	Status
5.1	phase1_gitea_unraid.sh	Deploy Gitea container, create admin user + token + org	TODO
5.2	phase1_post_check.sh	Verify Gitea HTTP 200, admin auth, token valid, org exists	TODO
5.3	phase1_teardown.sh	docker-compose down, optionally remove data	TODO

6. Phase 2 — Gitea on Fedora

#	File	Description	Status
6.1	phase2_gitea_fedora.sh	Deploy Gitea container on Fedora, create admin user + token	TODO
6.2	phase2_post_check.sh	Verify Fedora Gitea HTTP 200, admin auth, token valid	TODO
6.3	phase2_teardown.sh	docker-compose down on Fedora	TODO

7. Phase 3 — Runners

#	File	Description	Status
7.1	runners.conf.example	Runner definition format + example entries	DONE
7.2	manage_runner.sh	Add/remove/list runners dynamically (reads runners.conf)	TODO
7.3	phase3_runners.sh	Get registration token, deploy all runners defined in runners.conf	TODO
7.4	phase3_post_check.sh	Verify all runners from runners.conf are online in Gitea admin	TODO
7.5	phase3_teardown.sh	Stop + deregister all runners from runners.conf	TODO

8. Phase 4 — Migrate Repos + Fedora Mirrors

#	File	Description	Status
8.1	phase4_migrate_repos.sh	Import repos from GitHub, set up Fedora pull mirrors	TODO
8.2	phase4_post_check.sh	Verify repos on primary + mirror repos on Fedora	TODO
8.3	phase4_teardown.sh	Delete repos from primary + Fedora	TODO

9. Phase 5 — Migrate Pipelines

#	File	Description	Status
9.1	phase5_migrate_pipelines.sh	Copy .github/workflows/ → .gitea/workflows/, apply compat fixes	TODO
9.2	phase5_post_check.sh	Verify workflows visible in Gitea Actions UI	TODO
9.3	phase5_teardown.sh	Remove .gitea/workflows/ from repos	TODO

10. Phase 6 — GitHub Push Mirrors

#	File	Description	Status
10.1	phase6_github_mirrors.sh	Configure push mirrors from Gitea → GitHub	TODO
10.2	phase6_post_check.sh	Verify mirror config, trigger sync, check GitHub	TODO
10.3	phase6_teardown.sh	Remove push mirror config	TODO

11. Phase 7 — Branch Protection

#	File	Description	Status
11.1	phase7_branch_protection.sh	Set up branch protection rules on all repos	TODO
11.2	phase7_post_check.sh	Verify protection rules exist	TODO
11.3	phase7_teardown.sh	Delete branch protection rules	TODO

12. Phase 8 — Cutover (HTTPS + Archive GitHub)

#	File	Description	Status
12.1	phase8_cutover.sh	Nginx config + Certbot SSL + archive GitHub repos	TODO
12.2	phase8_post_check.sh	Verify HTTPS, repos accessible, mirrors working	TODO
12.3	phase8_teardown.sh	Remove Nginx config, reload, un-archive GitHub	TODO

13. Phase 9 — Security Scanning

#	File	Description	Status
13.1	phase9_security.sh	Deploy security workflow (Semgrep+Trivy+Gitleaks) to all repos	TODO
13.2	phase9_post_check.sh	Verify workflows exist, dry-run passes, branch protection updated	TODO
13.3	phase9_teardown.sh	Remove security workflows	TODO

14. Backup & Restore (post-migration operational scripts)

#	File	Description	Status
14.1	backup/backup_primary.sh	Run gitea dump on Unraid (DB + repos + config + users), SCP archive to Fedora	TODO
14.2	backup/restore_to_primary.sh	Restore a gitea dump archive to Unraid (fresh or existing instance)	TODO

15. Orchestration

#	File	Description	Status
15.1	run_all.sh	Run setup → preflight → phases 1-9 sequentially, --start-from=N	TODO
15.2	teardown_all.sh	Run teardowns in reverse, --through=N	TODO

16. Project Init

#	File	Description	Status
16.1	Git repo init + .gitignore	Initialize git repo, ignore .env and temp files	TODO
16.2	CLAUDE.md	Project-specific instructions for this codebase	TODO

17. Validation

#	File	Description	Status
17.1	Shellcheck all .sh files	Must pass with no errors	TODO
17.2	bash -n syntax check all scripts	Verify syntax without executing	TODO

---

Definition of Done — Every Item

1.1 — lib/common.sh

Depends on: nothing Steps:

1. Write shell library with set -euo pipefail
2. Implement every function listed below
3. Every function handles errors (non-zero exit, clear message)

Functions and their contracts:

Function	Inputs	Behavior	Returns
load_env	none	Sources .env, exports all vars. Exits 1 if .env missing.	0 on success
save_env_var KEY VALUE	key name, value string	If KEY exists in .env, replaces its line. If not, appends. Must not corrupt other lines.	0 on success
require_vars VAR1 VAR2...	variable names	For each: checks if exported and non-empty. Exits 1 naming the first missing var.	0 if all set
log_info MSG	message string	Prints [INFO] MSG to stderr in blue	—
log_warn MSG	message string	Prints [WARN] MSG to stderr in yellow	—
log_error MSG	message string	Prints [ERROR] MSG to stderr in red	—
log_success MSG	message string	Prints [OK] MSG to stderr in green	—
log_step N MSG	step number, message	Prints [N] MSG to stderr	—
phase_header NUM NAME	phase number, name	Prints \n=== Phase NUM: NAME ===\n to stderr	—
ssh_exec HOST_KEY CMD	host key (e.g. UNRAID), command string	Reads ${HOST_KEY}_IP, ${HOST_KEY}_SSH_USER, ${HOST_KEY}_SSH_PORT from env. Runs command via SSH with -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new. Streams stdout/stderr. Exits with remote exit code.	remote exit code
ssh_check HOST_KEY	host key	Same as ssh_exec but runs true. Returns 0 if reachable, 1 if not. Does NOT exit on failure.	0 or 1
scp_to HOST_KEY SRC DST	host key, local file path, remote file path	Copies local file to remote via SCP. Exits 1 if transfer fails.	0 on success
gitea_api METHOD PATH [DATA]	HTTP method, API path (e.g. /orgs), optional JSON body	Calls curl -s -X METHOD ${GITEA_INTERNAL_URL}/api/v1${PATH} with Authorization: token ${GITEA_ADMIN_TOKEN}. Exits 1 if HTTP status >= 400 (prints status + response body). Returns JSON response on stdout.	JSON on stdout
gitea_backup_api METHOD PATH [DATA]	same	Same as gitea_api but uses GITEA_BACKUP_INTERNAL_URL + GITEA_BACKUP_ADMIN_TOKEN	JSON on stdout
github_api METHOD PATH [DATA]	same	Calls https://api.github.com${PATH} with Authorization: token ${GITHUB_TOKEN}	JSON on stdout
render_template SRC DEST	.tpl file path, output path	Runs envsubst with all exported vars. Writes to DEST.	0 on success
wait_for_http URL MAX_SECS	URL, timeout in seconds	Polls with curl -sf -o /dev/null every 2 seconds. Exits 1 with timeout message if MAX_SECS exceeded.	0 when URL returns 200
wait_for_ssh HOST_KEY MAX_SECS	host key, timeout	Polls ssh_check every 2 seconds. Exits 1 on timeout.	0 when SSH connects

Done when:

• Every function above exists with exact signature
• shellcheck lib/common.sh passes with zero warnings
• bash -n lib/common.sh passes
• Sourcing the file (source lib/common.sh) does NOT execute anything — functions only, no side effects at source time
• save_env_var tested: set a var, read it back, value matches. Set it again with different value, only one line exists for that key.
• require_vars tested: prints the missing var's name, not a generic error
• ssh_exec uses ConnectTimeout to avoid hanging forever
• API functions return raw JSON on stdout (not mixed with log messages — logs go to stderr)

---

1.3 — contracts/gitea-api.md

Depends on: knowing all API calls used across phases 1-9 Steps:

1. For every Gitea API call in the project, document: method, path, request body, expected response, which script uses it
2. For every GitHub API call, same treatment
3. Cross-reference: every gitea_api/github_api call in any script MUST have a matching entry

API endpoints to document (complete list):

Endpoint	Used in
POST /api/v1/users/{user}/tokens	Phase 1, Phase 2 (generate admin token)
GET /api/v1/user	Preflight (validate token)
POST /api/v1/orgs	Phase 1 (create org)
GET /api/v1/orgs/{org}	Phase 1 (check if org exists)
POST /api/v1/repos/migrate	Phase 4 (import repos + Fedora mirrors)
GET /api/v1/repos/{owner}/{repo}	Phase 4 post-check (verify repo exists)
GET /api/v1/admin/runners/registration-token	Phase 3 (get runner token)
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}/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
DELETE /api/v1/repos/{owner}/{repo}	Phase 4 teardown
GET /api/v1/repos/{owner}/{repo}/actions/workflows	Phase 5 post-check
GitHub: GET /user	Preflight (validate GitHub token)
GitHub: GET /repos/{owner}/{repo}	Preflight (verify repos exist)
GitHub: PATCH /repos/{owner}/{repo}	Phase 8 (archive repos)

Done when:

• Every endpoint above is documented with: method, full path, request body schema, response schema, HTTP status codes
• Every gitea_api/github_api call in the codebase has a corresponding entry
• No endpoint is used in code but missing from the contract

---

2.1 — templates/docker-compose-gitea.yml.tpl

Depends on: .env vars defined Produces: Docker Compose file for Gitea + SQLite on a single host

Template must include:

• Gitea image pinned to $GITEA_VERSION
• Container name: gitea
• Volumes: $DATA_PATH/data:/data, $DATA_PATH/config:/data/gitea/conf
• Ports: $GITEA_PORT:3000, $GITEA_SSH_PORT:22 (add GITEA_SSH_PORT to .env if missing)
• Environment: USER_UID=1000, USER_GID=1000
• Restart policy: unless-stopped
• No database service (SQLite is file-based)

Variables used (must all be in .env): GITEA_VERSION, DATA_PATH, GITEA_PORT

Done when:

• render_template produces valid YAML (test with python3 -c "import yaml; yaml.safe_load(open('output.yml'))" or yq)
• No unexpanded $VAR or ${VAR} tokens in rendered output
• Container name is gitea (hardcoded, not variable — needed for docker exec)
• Volume paths use the variable, not hardcoded paths

---

2.2 — templates/app.ini.tpl

Depends on: .env vars defined Produces: Gitea configuration file

Must set:

• [security] INSTALL_LOCK = true — skip install wizard
• [server] ROOT_URL = https://$GITEA_DOMAIN/
• [server] SSH_DOMAIN = $GITEA_DOMAIN
• [server] DOMAIN = $GITEA_DOMAIN
• [database] DB_TYPE = $GITEA_DB_TYPE
• [database] PATH = /data/gitea/gitea.db
• [service] DISABLE_REGISTRATION = true — no public signups
• [actions] ENABLED = true — enable Gitea Actions
• [repository] DEFAULT_BRANCH = main
• [mailer] section left unconfigured (can be added later)

Done when:

• Rendered output is valid INI format
• INSTALL_LOCK = true is present (critical — without it, Gitea shows install wizard)
• ENABLED = true under [actions] (critical — without it, runners can't connect)
• No unexpanded variables

---

2.3 — templates/docker-compose-runner.yml.tpl

Depends on: .env vars, runner config Produces: Docker Compose file for act_runner on Linux

Must include:

• act_runner image: gitea/act_runner:$ACT_RUNNER_VERSION
• Container name: gitea-runner-$RUNNER_NAME
• Volume: Docker socket mount /var/run/docker.sock:/var/run/docker.sock (needed to spawn job containers)
• Volume: $RUNNER_DATA_PATH:/data
• Environment: GITEA_INSTANCE_URL, GITEA_RUNNER_REGISTRATION_TOKEN, GITEA_RUNNER_NAME, GITEA_RUNNER_LABELS
• Restart policy: unless-stopped

Done when:

• Rendered output is valid YAML
• Docker socket is mounted (without this, runner can't create job containers)
• Runner name and labels come from variables (not hardcoded)

---

2.4 — templates/runner-config.yaml.tpl

Depends on: act_runner config schema Produces: act_runner configuration file

Must set:

• runner.name: $RUNNER_NAME
• runner.labels: $RUNNER_LABELS
• runner.capacity: 1 (one concurrent job per runner — safe default)
• runner.timeout: 3h (max job duration)
• cache.enabled: true

Done when:

• Valid YAML after rendering
• Labels format is correct for act_runner (comma-separated label:scheme pairs)

---

2.5 — templates/com.gitea.runner.plist.tpl

Depends on: macOS launchd plist schema Produces: launchd service definition for act_runner on macOS

Must include:

• Label: com.gitea.runner.$RUNNER_NAME
• ProgramArguments: path to act_runner binary, daemon subcommand
• WorkingDirectory: $RUNNER_DATA_PATH
• RunAtLoad: true
• KeepAlive: true
• StandardOutPath / StandardErrorPath: log file locations

Done when:

• Valid XML plist (test with plutil -lint)
• Binary path matches where manage_runner.sh installs it
• KeepAlive ensures runner restarts if it crashes

---

2.6 — templates/nginx-gitea.conf.tpl

Depends on: .env vars Produces: Nginx server block for reverse-proxying Gitea

Must include:

• server_name $GITEA_DOMAIN
• listen 443 ssl
• ssl_certificate / ssl_certificate_key paths (Certbot standard: /etc/letsencrypt/live/$GITEA_DOMAIN/)
• proxy_pass http://$UNRAID_IP:$UNRAID_GITEA_PORT
• Proxy headers: X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, Host
• WebSocket support: proxy_set_header Upgrade, Connection "upgrade"
• HTTP→HTTPS redirect block (listen 80, return 301)
• client_max_body_size 512m (for large git pushes)

Done when:

• nginx -t passes against rendered config (can test by running nginx in Docker locally)
• WebSocket headers present (needed for Gitea's live features)
• HTTP→HTTPS redirect included
• SSL cert paths match Certbot convention

---

2.7 — templates/workflows/security-scan.yml.tpl

Depends on: Gitea Actions workflow syntax Produces: Shared security workflow for all repos

Must include:

• on: [pull_request] trigger
• Three jobs: semgrep, trivy, gitleaks
• Semgrep: returntocorp/semgrep:$SEMGREP_VERSION Docker image, semgrep scan --config auto .
• Trivy: aquasec/trivy:$TRIVY_VERSION, trivy fs --exit-code 1 --severity HIGH,CRITICAL .
• Gitleaks: zricethezav/gitleaks:$GITLEAKS_VERSION, gitleaks detect --source . --exit-code 1
• All three jobs must report as status checks (default behavior in Gitea Actions)

Done when:

• Valid YAML after rendering
• All three tools pinned to version vars (not latest hardcoded)
• Each job exits non-zero on findings (so branch protection can block merge)
• runs-on labels match what Linux runners advertise in runners.conf

---

3.1 — setup/configure_env.sh

Depends on: .env.example exists Runs: locally on MacBook (interactive — requires terminal input) Purpose: Guided wizard that prompts for every required .env variable, validates input, and writes a complete .env file.

Behavior:

1. If .env already exists, load current values as defaults (shown in brackets, press Enter to keep)
2. If .env does not exist, copy .env.example to .env first
3. Walk through each required variable in section order, prompting with:
   • Progress indicator: [12/47] ── GITEA SHARED CREDENTIALS ──────────────────
   • Variable name and description (from .env.example comments)
   • Current value if any (from existing .env): UNRAID_IP [192.168.1.10]:
   • Empty prompt if no current value: UNRAID_IP (Static IP of Unraid server):
4. Basic input validation per variable:
   • IP addresses: regex match ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$
   • Ports: integer between 1-65535
   • Passwords: minimum 8 characters
   • Emails: contains @
   • Paths: starts with /
   • URLs: starts with http:// or https://
5. After all prompts, write values to .env preserving the file structure (comments, sections)
6. Do NOT prompt for auto-populated vars (GITEA_ADMIN_TOKEN, GITEA_BACKUP_ADMIN_TOKEN, GITEA_RUNNER_REGISTRATION_TOKEN)
7. Do NOT prompt for vars with defaults unless user wants to change them — show default, press Enter to accept
8. Print summary at end showing all configured values (passwords masked)

Variable prompt order (matches .env.example sections):

#	Variable	Validation	Default
1	UNRAID_IP	IP address	—
2	UNRAID_SSH_USER	Non-empty	—
3	UNRAID_SSH_PORT	Port	22
4	UNRAID_GITEA_PORT	Port	3000
5	UNRAID_GITEA_SSH_PORT	Port	2222
6	UNRAID_GITEA_DATA_PATH	Absolute path	—
7	FEDORA_IP	IP address	—
8	FEDORA_SSH_USER	Non-empty	—
9	FEDORA_SSH_PORT	Port	22
10	FEDORA_GITEA_PORT	Port	3000
11	FEDORA_GITEA_SSH_PORT	Port	2222
12	FEDORA_GITEA_DATA_PATH	Absolute path	—
13	GITEA_ADMIN_USER	Non-empty	—
14	GITEA_ADMIN_PASSWORD	Min 8 chars	—
15	GITEA_ADMIN_EMAIL	Email	—
16	GITEA_ORG_NAME	Non-empty	—
17	GITEA_INSTANCE_NAME	Non-empty	—
18	GITEA_DB_TYPE	Non-empty	sqlite3
19	GITEA_VERSION	Non-empty	1.23
20	ACT_RUNNER_VERSION	Non-empty	0.2.11
21	GITEA_DOMAIN	Non-empty	—
22	GITEA_INTERNAL_URL	URL	—
23	GITEA_BACKUP_INTERNAL_URL	URL	—
24	GITEA_BACKUP_MIRROR_INTERVAL	Non-empty	8h
25	BACKUP_STORAGE_PATH	Absolute path	—
26	BACKUP_RETENTION_COUNT	Integer	5
27	GITHUB_USERNAME	Non-empty	—
28	GITHUB_TOKEN	Non-empty	—
29	REPO_1_NAME	Non-empty	—
30	REPO_2_NAME	Non-empty	—
31	REPO_3_NAME	Non-empty	—
32	MIGRATE_ISSUES	true/false	false
33	MIGRATE_LABELS	true/false	true
34	MIGRATE_MILESTONES	true/false	false
35	MIGRATE_WIKI	true/false	false
36	GITHUB_MIRROR_INTERVAL	Non-empty	8h
37	NGINX_CONTAINER_NAME	Non-empty	—
39	NGINX_CONF_PATH	Absolute path	—
40	SSL_MODE	letsencrypt or existing	letsencrypt
41	SSL_EMAIL	Email (only if SSL_MODE=letsencrypt)	—
42	SSL_CERT_PATH	Absolute path (only if SSL_MODE=existing)	—
43	SSL_KEY_PATH	Absolute path (only if SSL_MODE=existing)	—
44	PROTECTED_BRANCH	Non-empty	main
45	REQUIRE_PR_REVIEW	true/false	false
46	REQUIRED_APPROVALS	Integer	1
47	SEMGREP_VERSION	Non-empty	latest
48	TRIVY_VERSION	Non-empty	latest
49	GITLEAKS_VERSION	Non-empty	latest
50	SECURITY_FAIL_ON_ERROR	true/false	true

Done when:

• Each prompt shows progress: [N/50] with section header when entering a new section
• Running with no existing .env walks through all 50 prompts and produces a valid .env
• SSL prompts are conditional: if SSL_MODE=letsencrypt, prompt for SSL_EMAIL only; if SSL_MODE=existing, prompt for SSL_CERT_PATH and SSL_KEY_PATH only
• Running with an existing .env shows current values and only overwrites what user changes
• Invalid input (bad IP, path not starting with /, password too short) re-prompts with error message
• Auto-populated vars are skipped entirely (no prompt, no overwrite)
• Summary at end shows all values (passwords masked with ****)
• .env file preserves comment structure from .env.example
• shellcheck setup/configure_env.sh passes

---

3.2 — setup/macbook.sh

Depends on: nothing (first script to run) Runs: locally on MacBook

Steps:

1. Check for Homebrew → if missing, print install command and exit (don't auto-install — it's interactive)
2. brew install jq curl gettext shellcheck gh — skip any already installed
3. Verify built-in tools exist: ssh, git, scp, envsubst (from gettext)
4. Check Xcode CLI Tools: xcode-select -p → if fails, run xcode-select --install and wait
5. Print summary of what was installed vs already present

Idempotency: Running twice produces no errors and no redundant installs.

Done when:

• Running on a Mac where all tools exist prints "All prerequisites satisfied" and exits 0
• Running on a Mac missing jq installs it via brew and exits 0
• Script does NOT install Homebrew automatically (security — user should do it themselves)
• envsubst --version works after script runs (this is the most commonly missing tool)
• shellcheck setup/macbook.sh passes

---

3.3 — setup/unraid.sh

Depends on: SSH access to Unraid (.env vars: UNRAID_IP, UNRAID_SSH_USER, UNRAID_SSH_PORT) Runs: from MacBook via SSH into Unraid

Steps:

1. ssh_check UNRAID — fail if can't connect
2. Check Docker: ssh_exec UNRAID "docker --version" — if missing, exit 1 with message "Docker not found on Unraid. Install it via Unraid's Docker settings."
3. Check docker-compose: try docker compose version, then docker-compose --version. If neither works, download standalone docker-compose binary to /usr/local/bin/
4. Check jq: ssh_exec UNRAID "jq --version" — if missing, download static binary from GitHub releases to /usr/local/bin/jq, chmod +x
5. Verify data path: ssh_exec UNRAID "mkdir -p $UNRAID_GITEA_DATA_PATH && touch $UNRAID_GITEA_DATA_PATH/.write-test && rm $UNRAID_GITEA_DATA_PATH/.write-test"

Done when:

• docker --version works on Unraid via SSH
• docker compose version OR docker-compose --version works on Unraid via SSH
• jq --version works on Unraid via SSH
• UNRAID_GITEA_DATA_PATH exists and is writable
• Script does NOT attempt to install Docker on Unraid (could break Unraid's custom setup)
• shellcheck setup/unraid.sh passes

---

3.4 — setup/fedora.sh

Depends on: SSH access to Fedora (.env vars: FEDORA_IP, FEDORA_SSH_USER, FEDORA_SSH_PORT) Runs: from MacBook via SSH into Fedora

Steps:

1. ssh_check FEDORA — fail if can't connect
2. Check Docker: docker --version — if missing:
   • sudo dnf -y install dnf-plugins-core
   • sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
   • sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-compose-plugin
   • sudo systemctl enable --now docker
   • sudo usermod -aG docker $FEDORA_SSH_USER
   • Print warning: "User added to docker group. You may need to re-login for this to take effect."
3. Check jq: if missing, sudo dnf -y install jq
4. Verify Docker works: docker run --rm hello-world (must succeed without sudo after group membership)
5. Verify data path writable (same as Unraid step)

Done when:

• docker --version works on Fedora via SSH
• docker compose version works on Fedora via SSH
• jq --version works on Fedora via SSH
• docker run --rm hello-world succeeds without sudo (if it requires sudo, the docker group membership hasn't taken effect — script must warn about re-login)
• FEDORA_GITEA_DATA_PATH exists and is writable
• shellcheck setup/fedora.sh passes

---

4.1 — preflight.sh

Depends on: setup scripts completed, .env populated Runs: locally on MacBook Purpose: Pure validation. Installs nothing. Exits 0 only if EVERYTHING is ready.

Checks (each prints PASS/FAIL with specific message):

#	Check	Pass condition	Fail message
1	.env exists	File present in project root	".env not found. Copy .env.example to .env and fill in values."
2	runners.conf exists	File present in project root	"runners.conf not found. Copy runners.conf.example to runners.conf."
3	Required .env vars set	Every var in the list below is non-empty	"Missing required var: VAR_NAME"

Check #3 — Required variables (must be non-empty):

Section	Variable
Unraid	UNRAID_IP
Unraid	UNRAID_SSH_USER
Unraid	UNRAID_GITEA_DATA_PATH
Fedora	FEDORA_IP
Fedora	FEDORA_SSH_USER
Fedora	FEDORA_GITEA_DATA_PATH
Shared creds	GITEA_ADMIN_USER
Shared creds	GITEA_ADMIN_PASSWORD
Shared creds	GITEA_ADMIN_EMAIL
Shared creds	GITEA_ORG_NAME
Shared creds	GITEA_INSTANCE_NAME
Primary	GITEA_DOMAIN
Primary	GITEA_INTERNAL_URL
Backup	GITEA_BACKUP_INTERNAL_URL
Backup	BACKUP_STORAGE_PATH
Repos	GITHUB_USERNAME
Repos	GITHUB_TOKEN
Repos	REPO_1_NAME
Repos	REPO_2_NAME
Repos	REPO_3_NAME
Mirror	GITHUB_TOKEN
Nginx	NGINX_CONTAINER_NAME
Nginx	NGINX_CONF_PATH
Nginx	SSL_EMAIL

Not checked (have defaults or auto-populated): UNRAID_SSH_PORT, UNRAID_GITEA_PORT, UNRAID_GITEA_SSH_PORT, FEDORA_SSH_PORT, FEDORA_GITEA_PORT, FEDORA_GITEA_SSH_PORT, GITEA_DB_TYPE, GITEA_VERSION, ACT_RUNNER_VERSION, GITEA_BACKUP_MIRROR_INTERVAL, BACKUP_RETENTION_COUNT, MIGRATE_*, GITHUB_MIRROR_INTERVAL, PROTECTED_BRANCH, REQUIRE_PR_REVIEW, REQUIRED_APPROVALS, SEMGREP_VERSION, TRIVY_VERSION, GITLEAKS_VERSION, SECURITY_FAIL_ON_ERROR, GITEA_ADMIN_TOKEN, GITEA_BACKUP_ADMIN_TOKEN, GITEA_RUNNER_REGISTRATION_TOKEN | 4 | SSH to Unraid | ssh_check UNRAID returns 0 | "Cannot SSH to Unraid at $UNRAID_IP. Run setup/unraid.sh or check SSH config." | | 5 | SSH to Fedora | ssh_check FEDORA returns 0 | Same pattern | | 6 | Docker on Unraid | ssh_exec UNRAID "docker --version" exits 0 | "Docker not found on Unraid. Run setup/unraid.sh." | | 7 | Docker on Fedora | Same | Same | | 8 | docker-compose on Unraid | ssh_exec UNRAID "docker compose version" or docker-compose --version | "docker-compose not found on Unraid. Run setup/unraid.sh." | | 9 | docker-compose on Fedora | Same | Same | | 10 | Port 3000 free on Unraid | ssh_exec UNRAID "! ss -tlnp \| grep -q ':$UNRAID_GITEA_PORT '" | "Port $UNRAID_GITEA_PORT already in use on Unraid." | | 11 | Port 3000 free on Fedora | Same | Same | | 12 | DNS resolves | dig +short $GITEA_DOMAIN returns $UNRAID_IP | "$GITEA_DOMAIN does not resolve to $UNRAID_IP." | | 13 | GitHub token valid | github_api GET /user returns 200 | "GitHub token invalid. Check GITHUB_TOKEN in .env." | | 14 | GitHub repos exist | For each REPO_N_NAME: github_api GET /repos/$GITHUB_USERNAME/$REPO_N_NAME returns 200 | "GitHub repo $REPO_N_NAME not found under $GITHUB_USERNAME." | | 15 | Nginx running on Unraid | ssh_exec UNRAID "docker ps --filter name=$NGINX_CONTAINER_NAME --format '{{.Status}}'" contains "Up" | "Nginx container '$NGINX_CONTAINER_NAME' not running on Unraid." | | 16 | Nginx conf dir writable | ssh_exec UNRAID "test -w $NGINX_CONF_PATH" | "Nginx config path $NGINX_CONF_PATH not writable." |

Exit behavior: Runs ALL checks (doesn't stop at first failure). Prints summary at end. Exits 0 if all pass, 1 if any fail.

Done when:

• Every check in the table above is implemented
• Failed checks point to the correct setup script or config to fix
• All checks run even if earlier ones fail (user sees full picture)
• Exit code is 1 if ANY check fails, 0 only if ALL pass
• shellcheck preflight.sh passes

---

5.1 — phase1_gitea_unraid.sh

Depends on: preflight passed, templates exist Produces: Running Gitea instance on Unraid, admin user, API token in .env, org created require_vars: UNRAID_IP, UNRAID_SSH_USER, UNRAID_SSH_PORT, UNRAID_GITEA_PORT, UNRAID_GITEA_SSH_PORT, UNRAID_GITEA_DATA_PATH, GITEA_ADMIN_USER, GITEA_ADMIN_PASSWORD, GITEA_ADMIN_EMAIL, GITEA_ORG_NAME, GITEA_INSTANCE_NAME, GITEA_DB_TYPE, GITEA_VERSION, GITEA_INTERNAL_URL, GITEA_DOMAIN

Steps with idempotency:

#	Action	Idempotency check (skip if true)
1	Create data dirs on Unraid	ssh_exec UNRAID "test -d $UNRAID_GITEA_DATA_PATH/data"
2	Render + SCP docker-compose-gitea.yml.tpl	ssh_exec UNRAID "test -f $UNRAID_GITEA_DATA_PATH/docker-compose.yml"
3	Render + SCP app.ini.tpl	ssh_exec UNRAID "test -f $UNRAID_GITEA_DATA_PATH/config/app.ini"
4	docker-compose up -d on Unraid	ssh_exec UNRAID "docker ps --filter name=gitea --format '{{.Status}}'" contains "Up"
5	Wait for Gitea HTTP ready	curl -sf $GITEA_INTERNAL_URL/api/v1/version returns 200
6	Create admin user via docker exec gitea gitea admin user create	curl -sf -u $GITEA_ADMIN_USER:$GITEA_ADMIN_PASSWORD $GITEA_INTERNAL_URL/api/v1/user returns 200
7	Generate API token	GITEA_ADMIN_TOKEN is non-empty in .env AND gitea_api GET /user returns 200
8	Save token to .env	Token is in .env file
9	Create org	gitea_api GET /orgs/$GITEA_ORG_NAME returns 200

Done when:

• curl $GITEA_INTERNAL_URL returns Gitea HTML page
• curl -H "Authorization: token $GITEA_ADMIN_TOKEN" $GITEA_INTERNAL_URL/api/v1/user returns admin user JSON
• GITEA_ADMIN_TOKEN is written to .env and is non-empty
• Org exists: gitea_api GET /orgs/$GITEA_ORG_NAME returns 200
• Running the script again changes nothing (all steps skip with "already exists" messages)
• shellcheck phase1_gitea_unraid.sh passes

---

5.2 — phase1_post_check.sh

Depends on: phase1 completed Purpose: Independent verification that phase 1 succeeded (can be run separately)

Checks:

• Gitea responds at $GITEA_INTERNAL_URL with HTTP 200
• Admin user authenticates: curl -u user:pass .../api/v1/user returns 200
• API token works: gitea_api GET /user returns 200 with correct username
• Org exists: gitea_api GET /orgs/$GITEA_ORG_NAME returns 200
• Gitea Actions enabled: gitea_api GET /api/v1/settings/api or check app.ini

Done when:

• Runs all checks, prints PASS/FAIL for each
• Exits 0 only if ALL pass

---

5.3 — phase1_teardown.sh

Depends on: phase1 was run Destructive: yes — prompts for confirmation

Steps:

1. Prompt: "This will stop Gitea on Unraid. Continue? [y/N]"
2. ssh_exec UNRAID "cd $UNRAID_GITEA_DATA_PATH && docker-compose down"
3. Prompt: "Remove all Gitea data ($UNRAID_GITEA_DATA_PATH)? This is irreversible. [y/N]"
4. If confirmed: ssh_exec UNRAID "rm -rf $UNRAID_GITEA_DATA_PATH"
5. Clear GITEA_ADMIN_TOKEN from .env: save_env_var GITEA_ADMIN_TOKEN ""

Done when:

• Gitea container is stopped and removed
• Data is only deleted if user explicitly confirms
• GITEA_ADMIN_TOKEN is cleared from .env
• Running against an already-torn-down instance doesn't error

---

6.1 — phase2_gitea_fedora.sh

Depends on: preflight passed, templates exist Produces: Running Gitea instance on Fedora, admin user, API token in .env require_vars: FEDORA_IP, FEDORA_SSH_USER, FEDORA_SSH_PORT, FEDORA_GITEA_PORT, FEDORA_GITEA_SSH_PORT, FEDORA_GITEA_DATA_PATH, GITEA_ADMIN_USER, GITEA_ADMIN_PASSWORD, GITEA_ADMIN_EMAIL, GITEA_INSTANCE_NAME, GITEA_DB_TYPE, GITEA_VERSION, GITEA_BACKUP_INTERNAL_URL

Identical to phase1 except:

• Target: Fedora (uses FEDORA_IP, FEDORA_SSH_USER, FEDORA_SSH_PORT, FEDORA_GITEA_DATA_PATH, FEDORA_GITEA_PORT)
• Uses GITEA_BACKUP_INTERNAL_URL for API calls
• Saves token as GITEA_BACKUP_ADMIN_TOKEN
• Uses same admin credentials (GITEA_ADMIN_USER/GITEA_ADMIN_PASSWORD/GITEA_ADMIN_EMAIL)
• Does NOT create an org (mirrors will be under admin user's namespace)

Done when:

• Same criteria as 5.1 but targeting Fedora URLs/paths
• GITEA_BACKUP_ADMIN_TOKEN is in .env and works
• No org was created on Fedora instance

---

6.2 — phase2_post_check.sh

Same as 5.2 but targeting Fedora instance. No org check.

---

6.3 — phase2_teardown.sh

Same as 5.3 but targeting Fedora. Clears GITEA_BACKUP_ADMIN_TOKEN.

---

7.2 — manage_runner.sh

Depends on: lib/common.sh, runners.conf, templates Purpose: Standalone tool to add/remove/list individual runners

Subcommands:

manage_runner.sh add --name <runner_name>:

1. Read runner entry from runners.conf by name
2. If type=docker:
   • Render docker-compose-runner.yml.tpl with runner's vars
   • SCP to $DATA_PATH/docker-compose.yml on runner host
   • Render runner-config.yaml.tpl, SCP to $DATA_PATH/config.yaml
   • ssh_exec HOST "cd $DATA_PATH && docker-compose up -d"
   • wait_for_http on Gitea API for runner to appear
3. If type=native:
   • Download act_runner binary for host's OS/arch to $DATA_PATH/act_runner
   • Run $DATA_PATH/act_runner register --no-interactive --instance $GITEA_INTERNAL_URL --token $GITEA_RUNNER_REGISTRATION_TOKEN --name $NAME --labels $LABELS
   • Render launchd plist, copy to ~/Library/LaunchAgents/
   • launchctl load ~/Library/LaunchAgents/com.gitea.runner.$NAME.plist

manage_runner.sh remove --name <runner_name>:

1. Read runner entry from runners.conf
2. If type=docker: ssh_exec HOST "cd $DATA_PATH && docker-compose down", optionally rm data
3. If type=native: launchctl unload plist, rm binary + plist
4. Deregister from Gitea via API if possible (or just let it go offline)

manage_runner.sh list:

1. Read all entries from runners.conf
2. For each: query Gitea API for runner status
3. Print table: name, host, labels, type, status (online/offline)

Done when:

• add with a docker-type runner: container is running, runner appears in Gitea admin panel
• add with a native-type runner: launchd service is loaded, runner appears in Gitea admin panel
• remove stops the runner and it disappears from Gitea admin (or shows offline)
• list shows all runners with current status
• add on an already-deployed runner prints "already running" and exits 0
• remove on a non-existent runner prints warning and exits 0
• shellcheck manage_runner.sh passes

---

7.3 — phase3_runners.sh

Depends on: Phase 1 completed (Gitea running), runners.conf populated Produces: All runners from runners.conf deployed and registered require_vars: GITEA_INTERNAL_URL, GITEA_ADMIN_TOKEN (auto), ACT_RUNNER_VERSION

Steps:

1. Get registration token: gitea_api GET /admin/runners/registration-token
2. save_env_var GITEA_RUNNER_REGISTRATION_TOKEN <token>
3. For each entry in runners.conf: call manage_runner.sh add --name <name>

Done when:

• GITEA_RUNNER_REGISTRATION_TOKEN is in .env
• Every runner in runners.conf is deployed and shows "online" in Gitea admin
• Running again skips all already-deployed runners

---

7.4 — phase3_post_check.sh

Checks:

• For each runner in runners.conf: runner exists in Gitea admin API response
• For each runner in runners.conf: status is "online" (not just registered but idle/active)
• Runner count in Gitea matches line count in runners.conf

---

7.5 — phase3_teardown.sh

For each runner in runners.conf: manage_runner.sh remove --name <name>. Clears GITEA_RUNNER_REGISTRATION_TOKEN.

---

8.1 — phase4_migrate_repos.sh

Depends on: Phase 1 + Phase 2 completed (both Gitea instances running) Produces: All 3 repos on Unraid primary under org + pull mirrors on Fedora require_vars: GITEA_ADMIN_TOKEN (auto), GITEA_BACKUP_ADMIN_TOKEN (auto), GITEA_INTERNAL_URL, GITEA_BACKUP_INTERNAL_URL, GITEA_ORG_NAME, GITEA_ADMIN_USER, GITEA_ADMIN_PASSWORD, GITHUB_USERNAME, GITHUB_TOKEN, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME, MIGRATE_ISSUES, MIGRATE_LABELS, MIGRATE_MILESTONES, MIGRATE_WIKI, GITEA_BACKUP_MIRROR_INTERVAL

Steps:

For each REPO_N_NAME (N=1,2,3):

#	Action	API call	Idempotency check
1	Import repo from GitHub to Unraid	gitea_api POST /repos/migrate with clone_addr=https://github.com/$GITHUB_USERNAME/$REPO_N_NAME.git, auth_token=$GITHUB_TOKEN, repo_owner=$GITEA_ORG_NAME, repo_name=$REPO_N_NAME, mirror=false, issues=$MIGRATE_ISSUES, labels=$MIGRATE_LABELS, milestones=$MIGRATE_MILESTONES, wiki=$MIGRATE_WIKI	gitea_api GET /repos/$GITEA_ORG_NAME/$REPO_N_NAME returns 200
2	Wait for migration	Poll gitea_api GET /repos/$GITEA_ORG_NAME/$REPO_N_NAME until empty=false (repo has content)	—
3	Create pull mirror on Fedora	gitea_backup_api POST /repos/migrate with clone_addr=$GITEA_INTERNAL_URL/$GITEA_ORG_NAME/$REPO_N_NAME.git, auth_username=$GITEA_ADMIN_USER, auth_password=$GITEA_ADMIN_PASSWORD, repo_owner=$GITEA_BACKUP_ADMIN_USER, mirror=true, mirror_interval=$GITEA_BACKUP_MIRROR_INTERVAL	gitea_backup_api GET /repos/$GITEA_BACKUP_ADMIN_USER/$REPO_N_NAME returns 200

Done when:

• All 3 repos exist under $GITEA_ORG_NAME on Unraid with commits
• Each repo's default branch matches the GitHub source
• All 3 mirror repos exist on Fedora under admin user
• Fedora mirrors show mirror=true in API response
• Fedora mirrors have synced at least once (has commits)
• Running again skips all existing repos

---

8.2 — phase4_post_check.sh

Checks:

• Each repo exists on primary: gitea_api GET /repos/$ORG/$REPO returns 200
• Each repo has commits: gitea_api GET /repos/$ORG/$REPO/commits?limit=1 returns at least 1 commit
• Default branch matches source: compare default_branch field from Gitea vs GitHub API
• Each mirror repo exists on Fedora: gitea_backup_api GET /repos/$ADMIN/$REPO returns 200
• Each mirror has mirror: true in response

---

8.3 — phase4_teardown.sh

1. For each repo: gitea_api DELETE /repos/$GITEA_ORG_NAME/$REPO_N_NAME
2. For each mirror: gitea_backup_api DELETE /repos/$ADMIN/$REPO_N_NAME
3. Prompt before each deletion

---

9.1 — phase5_migrate_pipelines.sh

Depends on: Phase 4 completed (repos exist on Gitea) Produces: .gitea/workflows/ directory in each repo with adapted workflows require_vars: GITEA_ADMIN_TOKEN (auto), GITEA_INTERNAL_URL, GITEA_ORG_NAME, GITEA_ADMIN_USER, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME

Steps for each repo:

1. Clone repo from Gitea to temp dir: git clone $GITEA_INTERNAL_URL/$GITEA_ORG_NAME/$REPO.git /tmp/gitea-migration-$REPO
2. Check if .github/workflows/ exists — if not, log warning "No GitHub workflows found" and skip
3. Create .gitea/workflows/ directory
4. Copy all .yml files from .github/workflows/ to .gitea/workflows/
5. Apply compatibility fixes in each copied file:
   • Replace github.repository → gitea.repository in expressions
   • Replace github.event → gitea.event in expressions
   • Replace github.token → gitea.token
   • Replace github.server_url → gitea.server_url
   • Keep actions/checkout@v4 as-is (compatible with Gitea)
   • Add comment at top: # Migrated from GitHub Actions — review for Gitea compatibility
6. git add .gitea/, git commit -m "Migrate workflows to Gitea Actions", git push
7. Clean up temp dir

Idempotency: Skip repo if .gitea/workflows/ already exists with files.

Known limitations (document in script output):

• GitHub-specific marketplace actions may not work in Gitea — script logs warnings but doesn't block
• Self-hosted runner tool caches may differ — user may need to install tools manually
• OIDC/secrets need to be re-configured in Gitea settings

Done when:

• Each repo that had .github/workflows/ now has .gitea/workflows/ with adapted files
• Context variable replacements applied (github.* → gitea.*)
• Each adapted workflow file has the migration comment header
• Repos without workflows are skipped with a warning (not an error)
• Running again skips repos that already have .gitea/workflows/

---

9.2 — phase5_post_check.sh

Checks:

• Each repo has .gitea/workflows/ directory (check via API: gitea_api GET /repos/$ORG/$REPO/contents/.gitea/workflows)
• At least one .yml file in that directory
• Gitea Actions tab shows workflows (may require checking the Gitea web UI or API for action runs)

---

9.3 — phase5_teardown.sh

For each repo: clone, rm -rf .gitea/workflows, commit, push. Only if .gitea/workflows/ exists.

---

10.1 — phase6_github_mirrors.sh

Depends on: Phase 4 completed, GitHub mirror token set Produces: Push mirrors from Gitea → GitHub configured for all repos require_vars: GITEA_ADMIN_TOKEN (auto), GITEA_INTERNAL_URL, GITEA_ORG_NAME, GITHUB_USERNAME, GITHUB_TOKEN, GITHUB_MIRROR_INTERVAL, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME

Steps for each repo:

1. Check if push mirror already exists: gitea_api GET /repos/$ORG/$REPO/push_mirrors — skip if non-empty
2. Create push mirror: gitea_api POST /repos/$ORG/$REPO/push_mirrors with:
   • remote_address: https://github.com/$GITHUB_USERNAME/$REPO.git
   • remote_username: $GITHUB_USERNAME
   • remote_password: $GITHUB_TOKEN
   • interval: $GITHUB_MIRROR_INTERVAL
   • sync_on_commit: true
3. Trigger initial sync: gitea_api POST /repos/$ORG/$REPO/push_mirrors-sync
4. Disable GitHub Actions: github_api PATCH /repos/$GITHUB_USERNAME/$REPO with {"has_projects": false} — note: disabling Actions requires setting has_actions: false which may not be in the API. If not possible via API, print manual instructions.

Done when:

• Each repo has exactly one push mirror configured
• gitea_api GET /repos/$ORG/$REPO/push_mirrors returns the mirror config
• After triggering sync, GitHub repo has the same latest commit as Gitea
• Running again skips repos that already have mirrors

---

10.2 — phase6_post_check.sh

• Each repo: push mirror exists in API response
• Each repo: trigger sync and verify GitHub's latest commit SHA matches Gitea's HEAD

---

10.3 — phase6_teardown.sh

For each repo: gitea_api DELETE /repos/$ORG/$REPO/push_mirrors/{id}. Get mirror ID from list endpoint first.

---

11.1 — phase7_branch_protection.sh

Depends on: Phase 4 completed (repos exist) Produces: Branch protection on $PROTECTED_BRANCH for all repos require_vars: GITEA_ADMIN_TOKEN (auto), GITEA_INTERNAL_URL, GITEA_ORG_NAME, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME, PROTECTED_BRANCH, REQUIRE_PR_REVIEW, REQUIRED_APPROVALS

Steps for each repo:

1. Check if protection exists: gitea_api GET /repos/$ORG/$REPO/branch_protections/$PROTECTED_BRANCH — skip if 200
2. Create protection: gitea_api POST /repos/$ORG/$REPO/branch_protections with:
   • branch_name: $PROTECTED_BRANCH
   • enable_push: false
   • enable_push_whitelist: false
   • require_signed_commits: false
   • enable_status_check: true
   • enable_approvals_whitelist: $REQUIRE_PR_REVIEW
   • required_approvals: $REQUIRED_APPROVALS

Done when:

• Each repo: gitea_api GET /repos/$ORG/$REPO/branch_protections returns the rule
• Direct pushes to $PROTECTED_BRANCH are blocked
• Running again skips existing protections

---

11.2 / 11.3 — post-check and teardown

Post-check: verify protection rules via API. Teardown: gitea_api DELETE /repos/$ORG/$REPO/branch_protections/$PROTECTED_BRANCH.

---

12.1 — phase8_cutover.sh

Depends on: Nginx running on Unraid, all prior phases Produces: HTTPS access to Gitea, GitHub repos archived require_vars: UNRAID_IP, UNRAID_SSH_USER, UNRAID_SSH_PORT, UNRAID_GITEA_PORT, GITEA_INTERNAL_URL, GITEA_DOMAIN, GITEA_ADMIN_TOKEN (auto), GITEA_ORG_NAME, NGINX_CONTAINER_NAME, NGINX_CONF_PATH, SSL_EMAIL, GITHUB_USERNAME, GITHUB_TOKEN, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME

Steps with idempotency:

#	Action	Detail	Idempotency check (skip if true)
1	Deploy HTTP-only Nginx config	Render nginx-gitea.conf.tpl in HTTP-only mode (no SSL directives). This serves: (a) reverse proxy to Gitea on port 80, (b) /.well-known/acme-challenge/ location for Certbot webroot validation. SCP to $NGINX_CONF_PATH/gitea.conf.	ssh_exec UNRAID "test -f $NGINX_CONF_PATH/gitea.conf"
2	Test Nginx config	ssh_exec UNRAID "docker exec $NGINX_CONTAINER_NAME nginx -t" — if fails, remove config and exit 1	— (always run)
3	Reload Nginx (HTTP)	ssh_exec UNRAID "docker exec $NGINX_CONTAINER_NAME nginx -s reload"	—
4	Verify HTTP proxy works	curl -sf http://$GITEA_DOMAIN/api/v1/version returns 200	—
5	Obtain or verify SSL cert	If SSL_MODE=letsencrypt: ssh_exec UNRAID "docker run --rm -v /etc/letsencrypt:/etc/letsencrypt -v /var/www/html:/var/www/html certbot/certbot certonly --webroot -w /var/www/html -d $GITEA_DOMAIN --email $SSL_EMAIL --agree-tos --non-interactive". If SSL_MODE=existing: verify cert files exist at $SSL_CERT_PATH and $SSL_KEY_PATH on Unraid: ssh_exec UNRAID "test -f $SSL_CERT_PATH && test -f $SSL_KEY_PATH" — fail if missing.	letsencrypt: ssh_exec UNRAID "test -f /etc/letsencrypt/live/$GITEA_DOMAIN/fullchain.pem". existing: cert files already verified.
6	Deploy HTTPS Nginx config	Re-render nginx-gitea.conf.tpl in HTTPS mode (adds listen 443 ssl, cert paths, HTTP→HTTPS redirect). SCP to $NGINX_CONF_PATH/gitea.conf (overwrites HTTP-only version).	Cert exists from step 5
7	Test Nginx config (HTTPS)	ssh_exec UNRAID "docker exec $NGINX_CONTAINER_NAME nginx -t" — if fails, revert to HTTP-only config and exit 1	— (always run)
8	Reload Nginx (HTTPS)	ssh_exec UNRAID "docker exec $NGINX_CONTAINER_NAME nginx -s reload"	—
9	Verify HTTPS works	curl -sf https://$GITEA_DOMAIN/api/v1/version returns 200. Also: curl -sI https://$GITEA_DOMAIN to confirm no redirect loops.	—
10	Set up cert auto-renewal cron	Only if SSL_MODE=letsencrypt: ssh_exec UNRAID "echo '0 3 * * * docker run --rm -v /etc/letsencrypt:/etc/letsencrypt -v /var/www/html:/var/www/html certbot/certbot renew --quiet && docker exec $NGINX_CONTAINER_NAME nginx -s reload' | crontab -" — runs daily at 3 AM. If SSL_MODE=existing: skip (user manages their own cert renewal).	ssh_exec UNRAID "crontab -l 2>/dev/null | grep -q certbot"
11	Archive GitHub repos	For each repo: (a) Save original description: github_api GET /repos/$GITHUB_USERNAME/$REPO → store description field, (b) github_api PATCH /repos/$GITHUB_USERNAME/$REPO {"archived": true, "description": "[MOVED] Now at https://$GITEA_DOMAIN/$GITEA_ORG_NAME/$REPO — was: $ORIGINAL_DESCRIPTION"}	github_api GET /repos/$GITHUB_USERNAME/$REPO has "archived": true

Nginx template must support two render passes: The nginx-gitea.conf.tpl template is rendered with $SSL_ENABLED=true/false (set by the script, not .env):

• HTTP-only (SSL_ENABLED=false): listen 80, proxy_pass, ACME challenge location (if SSL_MODE=letsencrypt), no SSL directives
• HTTPS (SSL_ENABLED=true): listen 443 ssl, cert paths, listen 80 with 301 redirect, proxy_pass, WebSocket headers

Cert paths in the template depend on SSL_MODE:

• letsencrypt: ssl_certificate /etc/letsencrypt/live/$GITEA_DOMAIN/fullchain.pem, ssl_certificate_key /etc/letsencrypt/live/$GITEA_DOMAIN/privkey.pem
• existing: ssl_certificate $SSL_CERT_PATH, ssl_certificate_key $SSL_KEY_PATH

Certbot volume mounts:

• /etc/letsencrypt on Unraid host → mounted into both Certbot container and Nginx container
• /var/www/html on Unraid host → Nginx serves this for ACME challenges, Certbot writes challenge files here
• Verify these mount paths exist on the Nginx container: ssh_exec UNRAID "docker inspect $NGINX_CONTAINER_NAME --format '{{json .Mounts}}'" — if /etc/letsencrypt or webroot is not mounted, the script must fail with instructions to add the volume mounts to the Nginx container config.

Done when:

• https://$GITEA_DOMAIN returns valid HTTPS response (no cert errors)
• curl https://$GITEA_DOMAIN/api/v1/version returns Gitea version JSON
• Certificate is from Let's Encrypt: openssl s_client -connect $GITEA_DOMAIN:443 </dev/null 2>/dev/null | openssl x509 -noout -issuer contains "Let's Encrypt"
• HTTP requests redirect to HTTPS: curl -sI http://$GITEA_DOMAIN returns 301 with Location: https://...
• Cert auto-renewal cron is installed
• All GitHub repos show as archived with original description preserved in the new description
• Nginx config test passes before every reload (never reload a broken config)
• Running again skips cert generation, skips already-archived repos
• If Nginx container doesn't have required volume mounts, script fails with clear instructions

---

12.2 — phase8_post_check.sh

• HTTPS works with valid cert: curl -sf https://$GITEA_DOMAIN/ returns 200
• Certificate is from Let's Encrypt (not self-signed): check with openssl s_client
• All repos accessible: curl -sf https://$GITEA_DOMAIN/$ORG/$REPO returns 200
• GitHub repos are archived: github_api GET /repos/$USER/$REPO has "archived": true

---

12.3 — phase8_teardown.sh

1. Remove Nginx config: ssh_exec UNRAID "rm -f $NGINX_CONF_PATH/gitea.conf"
2. Reload Nginx: ssh_exec UNRAID "docker exec $NGINX_CONTAINER_NAME nginx -s reload"
3. Remove cert renewal cron: ssh_exec UNRAID "crontab -l 2>/dev/null | grep -v certbot | crontab -"
4. Prompt: "Remove SSL certificates for $GITEA_DOMAIN? [y/N]"
   • If yes: ssh_exec UNRAID "rm -rf /etc/letsencrypt/live/$GITEA_DOMAIN /etc/letsencrypt/archive/$GITEA_DOMAIN /etc/letsencrypt/renewal/$GITEA_DOMAIN.conf"
5. Un-archive GitHub repos: for each repo, github_api PATCH /repos/$GITHUB_USERNAME/$REPO {"archived": false}. Restore original description if it was saved in the archive description (parse after "was: ").

---

13.1 — phase9_security.sh

Depends on: Phase 5 completed (repos have .gitea/workflows/) Produces: Security scan workflow in all repos, branch protection updated require_vars: GITEA_ADMIN_TOKEN (auto), GITEA_INTERNAL_URL, GITEA_ORG_NAME, GITEA_ADMIN_USER, REPO_1_NAME, REPO_2_NAME, REPO_3_NAME, SEMGREP_VERSION, TRIVY_VERSION, GITLEAKS_VERSION, SECURITY_FAIL_ON_ERROR, PROTECTED_BRANCH

Steps for each repo:

1. Clone from Gitea to temp dir
2. Render security-scan.yml.tpl to .gitea/workflows/security-scan.yml
3. git add, git commit -m "Add security scanning workflow", git push
4. If SECURITY_FAIL_ON_ERROR=true: update branch protection to require status checks from security jobs
   • gitea_api PATCH /repos/$ORG/$REPO/branch_protections/$PROTECTED_BRANCH with status_check_contexts: ["semgrep", "trivy", "gitleaks"]

Idempotency: Skip if security-scan.yml already exists in repo.

Done when:

• Each repo has .gitea/workflows/security-scan.yml
• Workflow file references correct tool versions from .env
• If SECURITY_FAIL_ON_ERROR=true: branch protection includes the three status checks
• Creating a test PR triggers the security workflow (manual verification)

---

13.2 / 13.3 — post-check and teardown

Post-check: verify file exists in each repo via API, verify branch protection includes status checks. Teardown: remove file, update branch protection to remove status checks.

---

14.1 — backup/backup_primary.sh

Depends on: Phase 1 completed Produces: gitea-dump-*.zip archive on Fedora require_vars: UNRAID_IP, UNRAID_SSH_USER, UNRAID_SSH_PORT, UNRAID_GITEA_DATA_PATH, FEDORA_IP, FEDORA_SSH_USER, FEDORA_SSH_PORT, BACKUP_STORAGE_PATH, BACKUP_RETENTION_COUNT

Steps:

1. ssh_exec UNRAID "docker exec -u git gitea gitea dump -c /data/gitea/conf/app.ini -f /tmp/gitea-dump-$(date +%Y%m%d-%H%M%S).zip"
2. SCP dump from Unraid /tmp/ to $BACKUP_STORAGE_PATH/ on Fedora
3. Remove dump from Unraid /tmp/
4. Prune old backups: ssh_exec FEDORA "ls -t $BACKUP_STORAGE_PATH/gitea-dump-*.zip | tail -n +$((BACKUP_RETENTION_COUNT+1)) | xargs rm -f"
5. Print: backup file name, size, path on Fedora, remaining backup count

What's in the dump (verify these are captured):

• SQLite database (users, tokens, SSH keys, OAuth, webhooks, org/team membership, issues, PRs)
• All git repositories
• app.ini config

Done when:

• Zip file exists on Fedora at $BACKUP_STORAGE_PATH/
• Zip contains: gitea-db.sql (or gitea.db for SQLite), repos/ directory, app.ini
• Old backups beyond retention count are deleted
• Dump file on Unraid /tmp/ is cleaned up

---

14.2 — backup/restore_to_primary.sh

Depends on: A backup archive exists Produces: Restored Gitea instance on Unraid require_vars: UNRAID_IP, UNRAID_SSH_USER, UNRAID_SSH_PORT, UNRAID_GITEA_DATA_PATH, GITEA_INTERNAL_URL, GITEA_ADMIN_USER, GITEA_ADMIN_PASSWORD

Steps:

1. Accept --archive <path> (path on Fedora or local)
2. Prompt: "This will REPLACE all Gitea data on Unraid. Continue? [y/N]"
3. If archive is on Fedora: SCP to Unraid /tmp/
4. Stop Gitea: ssh_exec UNRAID "cd $UNRAID_GITEA_DATA_PATH && docker-compose down"
5. Back up current data (safety): ssh_exec UNRAID "mv $UNRAID_GITEA_DATA_PATH/data $UNRAID_GITEA_DATA_PATH/data.pre-restore"
6. Extract archive: ssh_exec UNRAID "cd $UNRAID_GITEA_DATA_PATH && unzip /tmp/gitea-dump-*.zip"
7. Move extracted files to correct locations (data, config)
8. Start Gitea: ssh_exec UNRAID "cd $UNRAID_GITEA_DATA_PATH && docker-compose up -d"
9. wait_for_http $GITEA_INTERNAL_URL 60
10. Verify admin login works: curl -sf -u $GITEA_ADMIN_USER:$GITEA_ADMIN_PASSWORD $GITEA_INTERNAL_URL/api/v1/user
11. Regenerate API token (old token from dump may conflict): create new token via basic auth, save_env_var GITEA_ADMIN_TOKEN

Done when:

• Gitea is running with restored data
• Admin can log in
• All repos are accessible
• All users from the backup exist
• New API token is generated and saved to .env
• Pre-restore data is preserved (not deleted) in case restore went wrong

---

15.1 — run_all.sh

Depends on: all scripts exist Steps:

1. Parse args: --start-from=N (default 0), --skip-setup
2. Define execution order array:
   • Step 0 — Setup:
     1. setup/configure_env.sh — interactive env wizard (populates .env)
     2. setup/macbook.sh — install MacBook prerequisites
     3. setup/unraid.sh — install Unraid prerequisites (via SSH)
     4. setup/fedora.sh — install Fedora prerequisites (via SSH)
   • Step P — Preflight: preflight.sh (validates everything before proceeding)
   • Steps 1-9 — Phases: phaseN_*.sh + phaseN_post_check.sh
3. Execute sequentially from start point
4. On any script exit code != 0: stop, print which step failed, print summary of what completed
5. On success: print full summary with checkmarks
6. --start-from=N (where N >= 1): skips setup + preflight only for phases. Still runs preflight.sh to validate .env vars (but NOT configure_env.sh or machine setup — assumes those were already done).

Done when:

• Running without args executes: configure_env → macbook → unraid → fedora → preflight → phase 1-9
• --start-from=3 skips phases 1-2 but still runs preflight, then starts at phase 3
• --skip-setup skips configure_env + machine setup scripts, starts at preflight
• Failure in any step stops execution (doesn't continue to next phase)
• Summary at end shows pass/fail for each step that ran

---

15.2 — teardown_all.sh

Steps:

1. Parse args: --through=N (default 1 = tear down everything)
2. Execute in REVERSE order: phase9_teardown → phase8_teardown → ... → phaseN_teardown
3. Each teardown prompts for confirmation (unless --yes flag)

Done when:

• --through=5 tears down phases 5-9 but leaves 1-4 intact
• Each phase teardown runs independently (doesn't fail because a later phase is already torn down)
• --yes skips all confirmation prompts

---

16.1 — Git repo + .gitignore

.gitignore must contain:

# Secrets — never commit
.env
runners.conf
*.pem
*.key
*.crt

# macOS
.DS_Store

# Temp files from script runs
/tmp/
*.log

# Backup archives
*.zip

# Editor / IDE
.vscode/
.idea/
*.swp
*~

Done when:

• git init completed
• .gitignore excludes .env, runners.conf, temp files
• .env.example and runners.conf.example are NOT ignored (they're templates)

---

16.2 — CLAUDE.md

Project-specific instructions for AI assistants working on this codebase.

Done when:

• Documents: project structure, how to run scripts, .env setup, script conventions
• Notes the set -euo pipefail + shellcheck requirement for all scripts

---

17.1 / 17.2 — Validation

Done when:

• shellcheck *.sh lib/*.sh setup/*.sh backup/*.sh exits 0 with zero warnings
• bash -n on every .sh file exits 0
• No file has unexpanded template variables (grep for \$[A-Z_] in rendered outputs should find nothing unexpected)

---

Git Commit Milestones

Each milestone is a git commit. Commit after all files in that group pass shellcheck and bash -n. Do not batch multiple milestones into one commit.

#	Commit message	Files included	Tracker sections
1	init: project structure, .gitignore, .env.example, runners.conf.example	.gitignore, .env.example, runners.conf.example, PLAN.md, CLAUDE.md	16.1, 16.2
2	feat: add shared library (lib/common.sh)	lib/common.sh	1.1
3	feat: add API contracts	contracts/gitea-api.md	1.3
4	feat: add configuration templates	templates/*.tpl, templates/workflows/*.tpl	2.1–2.7
5	feat: add setup scripts (configure_env, macbook, unraid, fedora)	setup/configure_env.sh, setup/macbook.sh, setup/unraid.sh, setup/fedora.sh	3.1–3.4
6	feat: add preflight validation	preflight.sh	4.1
7	feat: add Phase 1 — Gitea on Unraid	phase1_gitea_unraid.sh, phase1_post_check.sh, phase1_teardown.sh	5.1–5.3
8	feat: add Phase 2 — Gitea on Fedora	phase2_gitea_fedora.sh, phase2_post_check.sh, phase2_teardown.sh	6.1–6.3
9	feat: add Phase 3 — Runners	phase3_runners.sh, phase3_post_check.sh, phase3_teardown.sh, manage_runner.sh	7.2–7.5
10	feat: add Phase 4 — Migrate repos + Fedora mirrors	phase4_migrate_repos.sh, phase4_post_check.sh, phase4_teardown.sh	8.1–8.3
11	feat: add Phase 5 — Migrate pipelines	phase5_migrate_pipelines.sh, phase5_post_check.sh, phase5_teardown.sh	9.1–9.3
12	feat: add Phase 6 — GitHub push mirrors	phase6_github_mirrors.sh, phase6_post_check.sh, phase6_teardown.sh	10.1–10.3
13	feat: add Phase 7 — Branch protection	phase7_branch_protection.sh, phase7_post_check.sh, phase7_teardown.sh	11.1–11.3
14	feat: add Phase 8 — Cutover (HTTPS + archive GitHub)	phase8_cutover.sh, phase8_post_check.sh, phase8_teardown.sh	12.1–12.3
15	feat: add Phase 9 — Security scanning	phase9_security.sh, phase9_post_check.sh, phase9_teardown.sh	13.1–13.3
16	feat: add backup and restore scripts	backup/backup_primary.sh, backup/restore_to_primary.sh	14.1–14.2
17	feat: add orchestration (run_all.sh, teardown_all.sh)	run_all.sh, teardown_all.sh	15.1–15.2
18	chore: shellcheck + syntax validation fixes	Any files fixed during validation	17.1–17.2