Files
platform-core/infrastructure/ci/gitea-runner
DongHyeonka 69c3a732d5 feat(ci): add the desktop Gitea Actions runner configuration
The template repositories need a real runner for their CI, and the
owner chose one container on the desktop host (the k3s node).

Add compose.yaml and config.yaml for the official Gitea Runner 5.4.1
dind image, pinned by index digest, plus the operating guide. The
runner has capacity 1, one ubuntu-latest label pinned to
runner-images ubuntu-24.04-v26.11.03 by digest, restart: always, and
a 6 CPU / 10g cap (no more than half of the 12 cores and 31GiB).
Jobs use the dind daemon through the runner's Docker proxy for
Testcontainers; the host Docker socket is never mounted, job
containers stay unprivileged, valid_volumes is empty, and sweep
removes what a job created.

Dropped alternatives: the deprecated gitea/act_runner 0.6.1 (moved
to gitea/runner), the basic image with the host docker.sock (jobs
would own the host daemon), and dind-rootless (Testcontainers
compatibility needs separate checks).

Risk: the runner container is privileged; a job can still start a
privileged container on the inner daemon, so only trusted repository
workflows should run here. Runner jobs do not take the desktop's
heavy-work lock; the CPU and memory caps are the only guard.

Verification: config keys checked with `gitea-runner config get`,
`docker compose config` passes, the runner registered at user scope
and the Gitea API shows desktop-runner online and idle; it came back
online after `docker restart` without registering again.
2026-11-07 18:36:55 +09:00
..

Gitea Actions runner

Gitea Actions job을 실행하는 runner 하나를 desktop 호스트(k3s 노드 192.168.0.107)의 Docker 컨테이너로 운영한다. Kubernetes 리소스가 아니므로 host-nginx와 같이 호스트 설정의 버전 관리 위치로 둔다.

상태(2026-11-07): desktop-runner(id 1)를 donghyeon.kang 사용자 범위로 등록했다. Gitea API에서 online, busy=false, label ubuntu-latest다. 아직 job을 돌리지 않았으므로 Testcontainers 동작은 첫 CI job에서 확인한다. 아래 「적용 기록」을 본다.

결정

항목 값 이유
위치 desktop 호스트 Docker, 컨테이너 gitea-runner 소유자 결정(2026-11-07)
이미지 docker.io/gitea/runner:5.4.1-dind@sha256:8bcb489f9dd6be500de22bcaa8512ef57b81ae50315db8c7a1dc1b74978a76f4 공식 runner. gitea/act_runner는 Docker Hub에서 deprecated이고 gitea/runner로 옮겨졌다
동시 실행 runner.capacity: 1 desktop은 다른 빌드·Docker 작업과 함께 쓴다
label ubuntu-latest → docker.gitea.com/runner-images:ubuntu-24.04-v26.11.03@sha256:b96ba465021b1a4c6a1c9e79220c2b9bfad0f29b09dbb528bbfb35411443a3a4 공식 runner 이미지 하나, 날짜 태그와 digest로 고정
재시작 restart: always, Docker service enabled 컨테이너 종료·Docker 재시작·재부팅 뒤 다시 뜬다
등록 범위 사용자 donghyeon.kang 그 사용자 소유 repository의 job만 받는다
자원 상한 CPU 6, 메모리 10g 아래 「자원 상한」

버린 대안:

  • gitea/act_runner:0.6.1: Docker Hub 설명이 "Deprecated Gitea runner. Moved to gitea/runner"이고 2026-04-30 이후 갱신이 없다.
  • 호스트 docker.sock을 job에 주는 기본 이미지: job이 desktop Docker를 root처럼 쓴다.
  • -dind-rootless: 격리는 더 강하지만 Testcontainers 호환(rootless 소켓 경로, Ryuk, 포트 노출)을 따로 확인해야 해서 이번에는 고르지 않았다.

Java·Go 같은 큰 toolchain은 기본 runner 이미지에 없다. workflow가 actions/setup-java 같은 setup action으로 설치한다. 기본 이미지에는 Node.js, git, Docker CLI(Buildx, Compose 포함)가 있다.

job 안의 Docker와 위험

Testcontainers처럼 job이 Docker를 써야 하므로 job 컨테이너에 Docker API를 준다. 공식 runner가 주는 방법은 세 가지다.

방법 job이 쓰는 daemon 위험
기본 이미지 + 호스트 /var/run/docker.sock desktop 호스트 daemon job이 docker run --privileged -v /:/host로 호스트 root를 얻는다. 다른 컨테이너·이미지·볼륨도 지울 수 있다
-dind (선택) runner 컨테이너 안의 별도 daemon 호스트 소켓과 호스트의 다른 컨테이너에는 닿지 않는다. 다만 runner 컨테이너가 --privileged이므로, job이 안쪽 daemon에 privileged 컨테이너를 띄우면 여전히 호스트 장치에 닿을 수 있다
-dind-rootless runner 안의 rootless daemon(UID 1000) 탈출해도 UID 1000 권한이다. AppArmor rootlesskit 프로필, slirp4netns가 필요하고 Testcontainers 호환을 따로 확인해야 한다

고른 방법은 공식 문서가 권장하는 -dind다. 막은 것과 남은 것은 다음과 같다.

  • 호스트 Docker 소켓은 runner에도 job에도 mount하지 않는다. job은 runner의 Docker proxy를 거쳐 안쪽 daemon만 쓴다.
  • job 컨테이너는 privileged가 아니다(container.privileged: false). workflow의 container.options에 있는 --privileged, --cap-add, --device 같은 옵션은 runner가 버린다.
  • workflow가 호스트 경로나 runner 볼륨을 mount하지 못한다(container.valid_volumes: []).
  • job이 proxy로 만든 컨테이너·네트워크·볼륨은 job이 끝나면 지운다(container.sweep: true).
  • runner를 donghyeon.kang 사용자 범위로만 등록해 다른 사용자의 repository job은 받지 않는다.
  • 남은 위험: job이 Docker API로 안쪽 daemon에 --privileged 컨테이너를 띄우는 것은 proxy가 막지 않는다. 그래서 신뢰하는 repository의 workflow만 이 runner에서 돌린다. 외부 기여자의 fork PR workflow를 승인 없이 돌리지 않는다. 더 강한 격리가 필요하면 -dind-rootless나 job마다 새로 만드는 ephemeral VM으로 옮긴다.

자원 상한

desktop은 12코어, 메모리 31GiB다(2026-11-07 nproc, free -g). 다른 세션의 Gradle·Docker 게이트는 flock /tmp/claude-gates/heavy.lock으로 서로 순서를 지키지만 runner job은 그 lock을 쓰지 않는다. 그래서 runner 컨테이너에 상한을 걸어 job이 desktop 자원의 절반을 넘지 못하게 한다.

  • cpus: 6: 12코어의 절반이다.
  • mem_limit: 10g: 절반(15.5GiB)보다 작다. Gradle daemon과 test JVM, Testcontainers PostgreSQL 컨테이너를 함께 돌릴 여유를 두고, 다른 세션 게이트가 쓸 메모리를 남긴다.
  • dind 안의 daemon과 job 컨테이너가 모두 runner 컨테이너 cgroup 안에서 돌기 때문에 이 상한이 CI 작업 전체에 걸린다. 메모리가 넘치면 커널이 runner 컨테이너 안의 프로세스를 종료하므로 job이 OOM으로 실패한다. 그때는 상한을 올리기 전에 job의 JVM heap 설정부터 본다.

디스크와 정리

안쪽 daemon의 데이터(job 이미지, Testcontainers 이미지, 빌드 cache)는 이름 있는 볼륨 gitea-runner_docker에 쌓인다. desktop root 디스크는 228G 중 182G를 쓰고 있다(2026-11-07, 여유 34G). 예상 사용량은 다음과 같다.

항목 크기
runner 이미지(gitea/runner:5.4.1-dind) 약 133MB
job 이미지(runner-images:ubuntu-24.04) amd64 압축 543MB, 안쪽 daemon에서 2.325GB(2026-11-07 실측)
Testcontainers 이미지(PostgreSQL, Ryuk 등) 수백 MB
actions/cache(/data/cache) 상한 5GB

runner는 job이 끝나면 job 컨테이너와 proxy로 만든 컨테이너·네트워크·볼륨을 지우지만(container.sweep: true) 이미지는 지우지 않는다. 정리 주기는 다음과 같다.

  • 매주 한 번 사용량을 본다.

    docker system df -v | grep gitea-runner
    docker exec gitea-runner docker system df
    
  • 안쪽 사용량이 15GB를 넘거나 root 디스크 여유가 20G 아래로 내려가면 job이 없을 때 안쪽 이미지를 정리한다. 고정된 job 이미지도 지워지므로 다음 job이 압축 약 543MB를 다시 받는다.

    docker exec gitea-runner docker image prune -a -f
    docker exec gitea-runner docker builder prune -f
    
  • 볼륨 gitea-runner_docker 자체를 지우는 것은 runner를 완전히 지울 때만 한다 (「되돌리기」). 등록 파일이 있는 gitea-runner_data와 섞지 않는다.

파일과 위치

무엇 위치
원본 설정 이 디렉터리의 compose.yaml, config.yaml
desktop 실행 폴더 /home/donghyeon/.local/share/gitea-runner/ (compose.yaml, config.yaml, secrets/)
등록 파일 .runner Docker 볼륨 gitea-runner_data의 /data/.runner (runner 자격 증명, Secret으로 취급)
job 이미지·안쪽 daemon 데이터 Docker 볼륨 gitea-runner_docker (/var/lib/docker)
actions/cache 저장소 gitea-runner_data의 /data/cache, 상한 5GB

compose.yaml은 Git checkout에서 바로 실행하지 않는다. checkout의 branch가 바뀌면 runner 설정도 조용히 바뀌기 때문이다. 실행 폴더에 복사하고 SHA-256을 비교한다.

설치와 등록

전제: Gitea 서버에서 Actions가 켜져 있어야 한다 (Gitea 서비스). 등록 token은 사용자 donghyeon.kang의 설정 → Actions → Runners 화면이나 API POST /api/v1/user/actions/runners/registration-token(Gitea 1.27)에서 받는다. token은 runner를 등록할 수 있는 자격 증명이므로 출력·로그·Git에 남기지 않는다.

  1. 실행 폴더를 만들고 설정 두 개를 복사한다.

    install -d -m 0700 ~/.local/share/gitea-runner ~/.local/share/gitea-runner/secrets
    install -m 0644 infrastructure/ci/gitea-runner/compose.yaml infrastructure/ci/gitea-runner/config.yaml ~/.local/share/gitea-runner/
    sha256sum infrastructure/ci/gitea-runner/*.yaml ~/.local/share/gitea-runner/*.yaml
    
  2. 등록 token을 편집기로 ~/.local/share/gitea-runner/secrets/registration-token에 한 줄로 저장하고 권한을 0600으로 둔다.

  3. 이미지를 받고 digest를 확인한 뒤 시작한다.

    cd ~/.local/share/gitea-runner
    docker compose pull
    docker compose up -d
    docker compose logs runner
    

    처음 시작할 때 /data/.runner가 없으면 token file로 등록하고 daemon을 띄운다. 로그에 Runner registered successfully가 나와야 한다.

  4. 등록이 끝나면 token file을 지운다. .runner가 있으면 다시 읽지 않는다.

    rm ~/.local/share/gitea-runner/secrets/registration-token
    
  5. Gitea에서 runner가 online인지 본다. API GET /api/v1/user/actions/runners의 status가 online이고 label이 ubuntu-latest여야 한다.

운영

  • 상태: docker compose ps, docker compose logs --tail 100 runner
  • 설정 변경: 이 디렉터리를 고친 뒤 실행 폴더에 다시 복사하고 docker compose up -d --force-recreate. runner는 시작할 때만 설정을 읽는다. 재생성은 실행 중인 job을 취소하므로 job이 없을 때 한다.
  • 이미지 올리기: compose.yaml의 tag와 digest를 함께 바꾼다. 등록 파일은 그대로 유효하다. major가 바뀌면 Upgrading의 호환 변경을 먼저 읽는다.
  • 디스크: 「디스크와 정리」의 주기를 따른다.

되돌리기

runner만 내리기(등록 유지):

cd ~/.local/share/gitea-runner && docker compose down

runner를 완전히 지우기:

  1. Gitea 사용자 설정 → Actions → Runners에서 desktop-runner를 삭제한다.

  2. 컨테이너와 볼륨을 지운다. .runner와 job 이미지가 함께 사라진다.

    cd ~/.local/share/gitea-runner && docker compose down --volumes
    
  3. 실행 폴더 ~/.local/share/gitea-runner를 지운다.

Gitea 서버의 Actions까지 끄려면 services/gitea/profiles/oidc/values/baseline.yaml을 되돌리고 scripts/bootstrap/apply-gitea-oidc.sh --execute로 다시 적용한다.

적용 기록

2026-11-07 (KST)

  • 18:3x 서버: Gitea values 커밋 87dee1f를 소유자가 apply-gitea-oidc.sh --execute로 적용했다(manifest SHA-256 f082cba5…abbc). GET /api/v1/user/actions/runners가 200을 돌려주고 등록 token API가 동작한다.
  • 18:32 등록: 등록 token을 API로 받아 실행 폴더의 secrets/registration-token(0600)에 화면 출력 없이 저장하고 docker compose up -d로 시작했다. 로그에 Runner registered successfully, labels: [ubuntu-latest], declare successfully가 나왔다. 등록 뒤 token file을 지웠다.
  • 확인: Gitea API에서 desktop-runner id 1, status=online, busy=false. docker inspect에서 NanoCpus=6000000000, Memory=10737418240, Privileged=true, RestartPolicy=always, publish한 port 없음.
  • 안쪽 daemon: Docker 29.9.3, cgroup v2. compose network gitea-runner_default의 tcp://0.0.0.0:2376도 열리지만 --tlsverify이고 client 인증서가 컨테이너 밖에 없으며 host에 publish하지 않는다.
  • 재시작: docker restart gitea-runner 뒤 다시 등록하지 않고 같은 .runner로 daemon이 올라왔다. 호스트 재부팅은 시험하지 않았다(restart: always, Docker service enabled).
  • 첫 job을 빠르게 하려고 job 이미지를 안쪽 daemon에 미리 받았다. 안쪽 docker system df 2.325GB, 호스트 볼륨 gitea-runner_docker 2.234GB. root 디스크 여유는 34G에서 31G로 줄었다.
  • 등록 token은 Gitea에서 reset하기 전까지 다른 runner도 등록할 수 있다. 더 등록할 계획이 없으면 사용자 설정 → Actions → Runners에서 token을 reset한다.

출처