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.
13 KiB
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에 남기지 않는다.
-
실행 폴더를 만들고 설정 두 개를 복사한다.
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 -
등록 token을 편집기로
~/.local/share/gitea-runner/secrets/registration-token에 한 줄로 저장하고 권한을0600으로 둔다. -
이미지를 받고 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가 나와야 한다. -
등록이 끝나면 token file을 지운다.
.runner가 있으면 다시 읽지 않는다.rm ~/.local/share/gitea-runner/secrets/registration-token -
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를 완전히 지우기:
-
Gitea 사용자 설정 → Actions → Runners에서
desktop-runner를 삭제한다. -
컨테이너와 볼륨을 지운다.
.runner와 job 이미지가 함께 사라진다.cd ~/.local/share/gitea-runner && docker compose down --volumes -
실행 폴더
~/.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-256f082cba5…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-runnerid 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 networkgitea-runner_default의tcp://0.0.0.0:2376도 열리지만--tlsverify이고 client 인증서가 컨테이너 밖에 없으며 host에 publish하지 않는다. - 재시작:
docker restart gitea-runner뒤 다시 등록하지 않고 같은.runner로 daemon이 올라왔다. 호스트 재부팅은 시험하지 않았다(restart: always, Docker serviceenabled). - 첫 job을 빠르게 하려고 job 이미지를 안쪽 daemon에 미리 받았다. 안쪽
docker system df2.325GB, 호스트 볼륨gitea-runner_docker2.234GB. root 디스크 여유는 34G에서 31G로 줄었다. - 등록 token은 Gitea에서 reset하기 전까지 다른 runner도 등록할 수 있다. 더 등록할 계획이 없으면 사용자 설정 → Actions → Runners에서 token을 reset한다.