Validate Gitea runner instance URL

README.md

@@ -65,6 +65,8 @@ vi ops/gitea-runner/.env
 ./scripts/runner-up.sh
 ```
 
+`GITEA_INSTANCE_URL`은 SSH remote host가 아니라 브라우저에서 Gitea UI가 실제로 열리는 HTTP(S) root URL이어야 합니다. 예를 들어 `ssh://git@git.example.com:2222/org/repo.git`로 push하더라도 Gitea 웹이 `https://code.example.com`에서 열린다면 `GITEA_INSTANCE_URL=https://code.example.com`을 사용합니다. `./scripts/runner-up.sh`는 시작 전에 `${GITEA_INSTANCE_URL}/api/v1/version` 접근을 검사합니다.
+
 러너 상태와 로그:
 
 ```bash
@@ -81,10 +83,11 @@ runner는 `/var/run/docker.sock`을 mount하므로 이 머신의 Docker 권한
 
 `Cannot ping the Gitea instance server`와 `permission_denied: 403 Forbidden`이 반복되면 runner 컨테이너는 실행됐지만 Gitea가 등록을 거부한 상태입니다. 다음 순서로 처리합니다.
 
-1. Gitea instance와 repository에서 Actions가 활성화되어 있는지 확인합니다.
-2. admin settings에서 instance runner registration token을 새로 발급합니다.
-3. `ops/gitea-runner/.env`의 `GITEA_RUNNER_REGISTRATION_TOKEN` 값을 새 token으로 교체합니다.
-4. runner state를 초기화하고 재시작합니다.
+1. `GITEA_INSTANCE_URL`이 Gitea API를 가리키는지 확인합니다. `${GITEA_INSTANCE_URL}/api/v1/version`이 Gitea JSON을 반환해야 합니다.
+2. Gitea instance와 repository에서 Actions가 활성화되어 있는지 확인합니다.
+3. admin settings에서 instance runner registration token을 새로 발급합니다.
+4. `ops/gitea-runner/.env`의 `GITEA_RUNNER_REGISTRATION_TOKEN` 값을 새 token으로 교체합니다.
+5. runner state를 초기화하고 재시작합니다.
 
 ```bash
 cd ops/gitea-runner