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

ops/gitea-runner/.env.example

@@ -1,4 +1,4 @@
-GITEA_INSTANCE_URL=https://git.hananakick.cc
+GITEA_INSTANCE_URL=https://your-gitea.example.com
 GITEA_RUNNER_REGISTRATION_TOKEN=replace-with-instance-runner-token
 GITEA_RUNNER_NAME=openstock-runner
 GITEA_RUNNER_LABELS=ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest

scripts/runner-up.sh

@@ -16,6 +16,21 @@ if grep -q 'replace-with-.*-runner-token' "$ENV_FILE"; then
   exit 1
 fi
 
+INSTANCE_URL="$(sed -n 's/^GITEA_INSTANCE_URL=//p' "$ENV_FILE" | tail -n 1)"
+if [ -z "$INSTANCE_URL" ] || [ "$INSTANCE_URL" = "https://your-gitea.example.com" ]; then
+  echo "missing GITEA_INSTANCE_URL in $ENV_FILE" >&2
+  exit 1
+fi
+
+if command -v curl >/dev/null 2>&1; then
+  version_url="${INSTANCE_URL%/}/api/v1/version"
+  if ! curl -fsS "$version_url" >/dev/null 2>&1; then
+    echo "GITEA_INSTANCE_URL does not look reachable as a Gitea API endpoint: $version_url" >&2
+    echo "Use the exact Gitea web URL, not only the SSH host name." >&2
+    exit 1
+  fi
+fi
+
 cd "$RUNNER_DIR"
 docker compose up -d
 docker compose ps