Document instance runner setup

README.md

@@ -51,13 +51,13 @@ git push origin main v0.1.0
 
 | Requirement | Meaning |
 | --- | --- |
-| Gitea Actions | repository settings에서 Actions가 활성화되어 있어야 합니다. |
-| act runner | `ubuntu-latest` job을 실행할 runner가 등록되어 있어야 합니다. |
+| Gitea Actions | instance와 repository에서 Actions가 활성화되어 있어야 합니다. |
+| act runner | `ubuntu-latest` job을 실행할 전역 또는 repository runner가 등록되어 있어야 합니다. |
 | release permission | workflow의 `${{ secrets.GITEA_TOKEN }}`가 release 생성/asset 업로드 권한을 가져야 합니다. |
 
 ### Runner
 
-Docker 기반 Gitea act runner 구성은 `ops/gitea-runner`에 있습니다. 등록 토큰은 Gitea repository settings의 Actions runner 화면에서 발급받아 로컬 `.env`에만 저장합니다.
+Docker 기반 Gitea act runner 구성은 `ops/gitea-runner`에 있습니다. 기본 운영 방식은 전역(instance) runner입니다. 등록 토큰은 Gitea admin settings의 Actions runner 화면에서 발급받아 로컬 `.env`에만 저장합니다.
 
 ```bash
 cp ops/gitea-runner/.env.example ops/gitea-runner/.env
@@ -77,12 +77,12 @@ vi ops/gitea-runner/.env
 ./scripts/runner-down.sh
 ```
 
-runner는 `/var/run/docker.sock`을 mount하므로 이 머신의 Docker 권한을 가진 신뢰 가능한 저장소에만 연결해야 합니다. `ops/gitea-runner/.env`와 `ops/gitea-runner/data/`는 registration token과 runner state를 포함할 수 있어 git에서 제외합니다.
+runner는 `/var/run/docker.sock`을 mount하므로 이 머신의 Docker 권한을 가진 신뢰 가능한 repository에서만 사용해야 합니다. 전역 runner는 여러 repository가 공유할 수 있으므로 Gitea instance에서 runner 사용 범위를 신뢰 가능한 repository로 제한해 운영합니다. `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을 새로 발급합니다.
+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를 초기화하고 재시작합니다.
 

ops/gitea-runner/.env.example

@@ -1,4 +1,4 @@
 GITEA_INSTANCE_URL=https://git.hananakick.cc
-GITEA_RUNNER_REGISTRATION_TOKEN=replace-with-repository-runner-token
+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

@@ -11,7 +11,7 @@ if [ ! -f "$ENV_FILE" ]; then
   exit 1
 fi
 
-if grep -q 'replace-with-repository-runner-token' "$ENV_FILE"; then
+if grep -q 'replace-with-.*-runner-token' "$ENV_FILE"; then
   echo "missing GITEA_RUNNER_REGISTRATION_TOKEN in $ENV_FILE" >&2
   exit 1
 fi
@@ -21,6 +21,6 @@ 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 "If logs repeat 'permission_denied: 403 Forbidden', refresh the instance runner registration token in Gitea and update:"
 echo "$ENV_FILE"
 echo "Then restart with: docker compose down && docker compose up -d"