# 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`) 이미지는 지우지 않는다. 정리 주기는 다음과 같다. - 매주 한 번 사용량을 본다. ```bash docker system df -v | grep gitea-runner docker exec gitea-runner docker system df ``` - 안쪽 사용량이 15GB를 넘거나 root 디스크 여유가 20G 아래로 내려가면 job이 없을 때 안쪽 이미지를 정리한다. 고정된 job 이미지도 지워지므로 다음 job이 압축 약 543MB를 다시 받는다. ```bash 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 서비스](../../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 ~/.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를 확인한 뒤 시작한다. ```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/)의 호환 변경을 먼저 읽는다. - 디스크: 「디스크와 정리」의 주기를 따른다. ## 되돌리기 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)