From 164346c61f38557226e3eec8d7a91fc7db67c9c3 Mon Sep 17 00:00:00 2001
From: Hana <bbggkkk@naver.com>
Date: Tue, 9 Jun 2026 15:13:22 +0900
Subject: [PATCH] Document Gitea runner 403 recovery

---
 README.md            | 15 +++++++++++++++
 scripts/runner-up.sh |  5 +++++
 2 files changed, 20 insertions(+)

diff --git a/README.md b/README.md
index 44555e6..2826fb7 100644
--- a/README.md
+++ b/README.md
@@ -79,6 +79,21 @@ vi ops/gitea-runner/.env
 
 runner는 `/var/run/docker.sock`을 mount하므로 이 머신의 Docker 권한을 가진 신뢰 가능한 저장소에만 연결해야 합니다. `ops/gitea-runner/.env`와 `ops/gitea-runner/data/`는 registration token과 runner state를 포함할 수 있어 git에서 제외합니다.
 
+`Cannot ping the Gitea instance server`와 `permission_denied: 403 Forbidden`이 반복되면 runner 컨테이너는 실행됐지만 Gitea가 등록을 거부한 상태입니다. 다음 순서로 처리합니다.
+
+1. Gitea repository settings에서 Actions가 활성화되어 있는지 확인합니다.
+2. repository scope의 runner registration token을 새로 발급합니다.
+3. `ops/gitea-runner/.env`의 `GITEA_RUNNER_REGISTRATION_TOKEN` 값을 새 token으로 교체합니다.
+4. runner state를 초기화하고 재시작합니다.
+
+```bash
+cd ops/gitea-runner
+docker compose down
+rm -rf data
+docker compose up -d
+docker compose logs --tail=120 openstock-runner
+```
+
 ## Architecture
 
 | Layer | Path | Role |
diff --git a/scripts/runner-up.sh b/scripts/runner-up.sh
index ef80cec..240e1fd 100755
--- a/scripts/runner-up.sh
+++ b/scripts/runner-up.sh
@@ -19,3 +19,8 @@ fi
 cd "$RUNNER_DIR"
 docker compose up -d
 docker compose ps
+
+echo
+echo "If logs repeat 'permission_denied: 403 Forbidden', refresh the repository runner registration token in Gitea and update:"
+echo "$ENV_FILE"
+echo "Then restart with: docker compose down && docker compose up -d"