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.
This commit is contained in:
@@ -0,0 +1,232 @@
|
||||
# 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)
|
||||
@@ -0,0 +1,40 @@
|
||||
# Single Gitea Actions runner on the desktop host (docker compose).
|
||||
# Copy this file and config.yaml to the runtime folder named in README.md
|
||||
# and run `docker compose up -d` there. Do not run it from a Git checkout.
|
||||
name: gitea-runner
|
||||
|
||||
services:
|
||||
runner:
|
||||
# Official Gitea Runner 5.4.1, dind flavour, pinned by index digest.
|
||||
image: docker.io/gitea/runner:5.4.1-dind@sha256:8bcb489f9dd6be500de22bcaa8512ef57b81ae50315db8c7a1dc1b74978a76f4
|
||||
container_name: gitea-runner
|
||||
hostname: desktop-runner
|
||||
# Starts again after a crash, a Docker restart and a host reboot.
|
||||
restart: always
|
||||
# Required by the bundled Docker daemon that runs the jobs. Jobs never
|
||||
# see the host Docker socket. See README.md for what this still allows.
|
||||
privileged: true
|
||||
environment:
|
||||
GITEA_INSTANCE_URL: https://git.learn.hyeonworks.com
|
||||
GITEA_RUNNER_NAME: desktop-runner
|
||||
# Read only while /data/.runner does not exist yet.
|
||||
GITEA_RUNNER_REGISTRATION_TOKEN_FILE: /run/gitea-runner/registration-token
|
||||
CONFIG_FILE: /config.yaml
|
||||
volumes:
|
||||
- ./config.yaml:/config.yaml:ro
|
||||
- ./secrets:/run/gitea-runner:ro
|
||||
- data:/data
|
||||
- docker:/var/lib/docker
|
||||
# Every job container runs inside this container's cgroup, so these
|
||||
# limits cap all CI work on the shared desktop.
|
||||
cpus: 6
|
||||
mem_limit: 10g
|
||||
logging:
|
||||
driver: json-file
|
||||
options:
|
||||
max-size: 10m
|
||||
max-file: "3"
|
||||
|
||||
volumes:
|
||||
data:
|
||||
docker:
|
||||
@@ -0,0 +1,38 @@
|
||||
# Gitea Runner 5.4.1 configuration for the single desktop runner.
|
||||
# Every key not listed here keeps the default printed by
|
||||
# `gitea-runner config generate` for that version.
|
||||
|
||||
log:
|
||||
level: info
|
||||
|
||||
runner:
|
||||
# The dind image starts in /data, a named volume. The registration file
|
||||
# holds the runner credential and must stay on that volume.
|
||||
file: .runner
|
||||
# One job at a time. The desktop also runs other build and Docker work.
|
||||
capacity: 1
|
||||
# The only label. runs-on: ubuntu-latest runs in this image, pinned by tag
|
||||
# and index digest so a moved tag cannot change the job environment.
|
||||
labels:
|
||||
- "ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-24.04-v26.11.03@sha256:b96ba465021b1a4c6a1c9e79220c2b9bfad0f29b09dbb528bbfb35411443a3a4"
|
||||
|
||||
cache:
|
||||
enabled: true
|
||||
dir: /data/cache
|
||||
# The desktop root disk is shared. Bound the actions/cache store.
|
||||
size_limit: 5GB
|
||||
|
||||
container:
|
||||
# Job containers stay unprivileged. Workflow options that could escape the
|
||||
# container (--privileged, --cap-add, --device, ...) are dropped.
|
||||
privileged: false
|
||||
# Workflows may not bind-mount runner volumes or host paths.
|
||||
valid_volumes: []
|
||||
# Empty: jobs get the runner's own Docker daemon (the dind daemon inside
|
||||
# the runner container) through the runner's Docker proxy, so
|
||||
# Testcontainers works. The host Docker socket is never mounted.
|
||||
docker_host: ""
|
||||
# CI-only runner: remove the containers, networks and volumes a job
|
||||
# created through the proxy when the job ends.
|
||||
sweep: true
|
||||
force_pull: false
|
||||
Reference in New Issue
Block a user