# 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 루트 SSD에 있고, 운영 k3s와 같은 디스크다. 설치 이틀 만에 16G가 됐다(2026-11-09: 이미지 12.35G, 빌드 cache 3.4G). 2026-11-11에는 이미지 12.43G, 빌드 cache 8.44G였다. 상한은 두 가지로 건다. | 무엇 | 방법 | 값 | | --- | --- | --- | | 빌드 cache | `daemon.json`의 BuildKit GC. 안쪽 daemon이 스스로 지운다 | 최소 2GB, 상한 10GB. 디스크 여유가 35GB 아래면 2GB까지 | | job 이미지 | 호스트 systemd timer `gitea-runner-prune.timer`. 주 1회 | 만든 지 7일 지난 안 쓰는 이미지, 3일 지난 빌드 cache | | actions/cache | `config.yaml`의 `cache.size_limit` | 5GB | - BuildKit 키의 뜻과 값을 고른 이유는 [호스트 설정](../../host/README.md)의 「BuildKit 상한 값」에 있다. 호스트와 같은 키에 더 작은 값을 쓴다. - Docker daemon은 이미지를 스스로 지우지 않는다. 그래서 이미지는 timer로 지운다. - `image prune --filter until=168h`는 이미지를 **만든** 시각으로 거른다. 마지막으로 쓴 시각이 아니다. 그래서 고정한 job 이미지(`runner-images:ubuntu-24.04`, 2026-11-03 생성)도 지워지고, 다음 job이 압축 약 543MB를 다시 받는다. 실행 중인 job 컨테이너가 쓰는 이미지는 지워지지 않는다. - timer는 일요일 04:30(KST)에 돈다. 그 시각에 꺼져 있었으면 다음 부팅 때 돈다 (`Persistent=true`). service는 `donghyeon` 사용자(docker group)로 돌아 root가 필요 없다. 설치(소유자, sudo 한 번): ```bash sudo install -m 0644 infrastructure/ci/gitea-runner/gitea-runner-prune.service \ infrastructure/ci/gitea-runner/gitea-runner-prune.timer /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now gitea-runner-prune.timer systemctl list-timers gitea-runner-prune.timer ``` 바로 한 번 돌리려면 job이 없을 때 `sudo systemctl start gitea-runner-prune.service`를 실행하고 `journalctl -u gitea-runner-prune.service -n 30`으로 결과를 본다. 되돌리기: ```bash sudo systemctl disable --now gitea-runner-prune.timer sudo rm /etc/systemd/system/gitea-runner-prune.service /etc/systemd/system/gitea-runner-prune.timer sudo systemctl daemon-reload ``` 사용량 보기: ```bash docker system df -v | grep gitea-runner docker exec gitea-runner docker system df docker exec gitea-runner docker buildx inspect default | sed -n '/GC Policy rule#1/,/Min Free/p' ``` 볼륨 `gitea-runner_docker` 자체를 지우는 것은 runner를 완전히 지울 때만 한다 (「되돌리기」). 등록 파일이 있는 `gitea-runner_data`와 섞지 않는다. ## 파일과 위치 | 무엇 | 위치 | | --- | --- | | 원본 설정 | 이 디렉터리의 `compose.yaml`, `config.yaml`, `daemon.json` | | 주 1회 정리 | 이 디렉터리의 `gitea-runner-prune.service`·`.timer` → `/etc/systemd/system/` | | desktop 실행 폴더 | `/home/donghyeon/.local/share/gitea-runner/` (`compose.yaml`, `config.yaml`, `daemon.json`, `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 서비스](../../services/gitea/README.md)). 등록 token은 사용자 `donghyeon.kang`의 설정 → Actions → Runners 화면이나 API `POST /api/v1/user/actions/runners/registration-token`(Gitea 1.27)에서 받는다. token은 runner를 등록할 수 있는 자격 증명이므로 출력·로그·Git에 남기지 않는다. 1. 실행 폴더를 만들고 설정 두 개를 복사한다. ```bash 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 \ infrastructure/ci/gitea-runner/daemon.json ~/.local/share/gitea-runner/ sha256sum infrastructure/ci/gitea-runner/{compose.yaml,config.yaml,daemon.json} \ ~/.local/share/gitea-runner/{compose.yaml,config.yaml,daemon.json} ``` 2. 등록 token을 편집기로 `~/.local/share/gitea-runner/secrets/registration-token`에 한 줄로 저장하고 권한을 `0600`으로 둔다. 3. 이미지를 받고 digest를 확인한 뒤 시작한다. ```bash 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`가 있으면 다시 읽지 않는다. ```bash 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](https://docs.gitea.com/runner/upgrade/)의 호환 변경을 먼저 읽는다. - 디스크: 「디스크와 정리」의 상한과 timer가 맡는다. 매주 `list-timers`로 마지막 실행을 본다. ## 되돌리기 runner만 내리기(등록 유지): ```bash cd ~/.local/share/gitea-runner && docker compose down ``` runner를 완전히 지우기: 1. Gitea 사용자 설정 → Actions → Runners에서 `desktop-runner`를 삭제한다. 2. 컨테이너와 볼륨을 지운다. `.runner`와 job 이미지가 함께 사라진다. ```bash 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한다. ## 출처 - [Gitea Runner: Install with Docker](https://docs.gitea.com/runner/installation/docker/) - [Gitea Runner: Registration](https://docs.gitea.com/runner/registration/) - [Gitea Runner: Configuration](https://docs.gitea.com/runner/configuration/), [Example configuration](https://docs.gitea.com/runner/reference/config-example/) - [Gitea Runner: Labels](https://docs.gitea.com/runner/labels/), [Jobs (Docker inside jobs)](https://docs.gitea.com/runner/jobs/) - [gitea/runner v5.4.1 release](https://gitea.com/gitea/runner/releases/tag/v5.4.1), [container.sweep opt-in 변경](https://gitea.com/gitea/runner/pulls/1389) - [gitea/runner-images](https://gitea.com/gitea/runner-images) - [Gitea 1.27 config cheat sheet: Actions, Repository](https://docs.gitea.com/1.27/administration/config-cheat-sheet)