# Gitea 서비스 Gitea는 같은 공식 Helm Chart와 공통 values를 사용하는 두 Kustomize 빌드 루트로 관리한다. 업스트림 Chart 템플릿은 복제하거나 수정하지 않는다. | 용도 | 빌드 루트 | 검증 산출물 | 적용 진입점 | | --- | --- | --- | --- | | 신규 설치 baseline | `services/gitea` | `gitea.yaml` | `apply-phase1-gitea.sh` | | OIDC·브랜딩 목표 상태 | `services/gitea/profiles/oidc` | `gitea-oidc.yaml` | `apply-gitea-oidc.sh` | baseline 루트는 OIDC Secret, `id` host alias, Keycloak 전용 egress와 브랜딩을 포함하지 않는다. OIDC profile만 공통 기반에 이 네 요소를 추가한다. 상태(2026-07-23): Host Nginx public discovery 전환과 OIDC-enabled Gitea rollout을 완료했다. 적용 manifest SHA-256은 `d25a757...a157`이며, 활성 `keycloak` OAuth2 source, 외부 인증 전용 가입 정책, authorization-code redirect와 아래 선언형 브랜딩의 자동 검증을 모두 통과했다. 실제 realm 사용자의 브라우저 login/callback/logout, 비상 관리자 실제 로그인과 Pod 재시작 뒤 설정 지속성은 별도 수용 시험으로 남아 있다. 상태(2026-11-07): Actions와 Package Registry를 켠 values(커밋 `87dee1f`)를 같은 진입점 `apply-gitea-oidc.sh --execute`로 적용했다. 적용 manifest SHA-256은 `f082cba5ca22b97ed5a463414404b852a4cfd452a0dd40c6e3b4b5f3afd4abbc`이고 스크립트의 rollout·OAuth2 source·로그인 흐름·브랜딩 검사를 모두 통과했다. 적용 전후 health, 웹, Git HTTPS, OIDC discovery, 사용자 repository 24개와 PR이 같았다. ## 고정된 업스트림 릴리스 | 항목 | 값 | | --- | --- | | Chart 저장소 | `https://dl.gitea.com/charts/` | | Chart | `gitea` | | Chart 버전 | `12.7.0` | | Chart 패키지 SHA-256 | `5881ef9c59400bee2d5547e77c4cd0efb925143c2f5d93fb4f38446db76b0167` | | Gitea 이미지 | `docker.gitea.com/gitea:1.27.0-rootless` | Chart는 렌더링할 때 저장소 공통 `.gitignore`에서 제외한 `profiles/oidc/.helm/charts`에 내려받는다. baseline 루트와 OIDC profile이 이 고정 SHA 검증 캐시 하나를 각자의 `chartHome`으로 참조한다. values와 Patch는 모두 `services/gitea` 아래에 있으므로 Kustomize의 기본 `RootOnly` 로드 제한을 유지한다. ## baseline과 OIDC 로그인 정책 두 프로필이 공유하는 `profiles/oidc/values/baseline.yaml`은 다음 정책을 선언한다. - 자체 가입을 닫고(`DISABLE_REGISTRATION=true`) 외부 인증 전용 가입도 끈다. - 가입 버튼을 숨기고 기존 `gitea-admin` 로컬 비상 로그인을 유지한다. - PostgreSQL, PVC, probe, resource와 restricted securityContext를 공통으로 둔다. `profiles/oidc/values/oidc.yaml`은 baseline 위에 다음 항목만 덮어쓴다. - `APP_NAME=Hyeonworks Git`으로 브라우저 제목과 애플리케이션 이름을 고정한다. - `DISABLE_REGISTRATION=false`와 `ALLOW_ONLY_EXTERNAL_REGISTRATION=true`를 함께 사용해 Keycloak 같은 외부 인증을 통한 신규 사용자 생성만 허용한다. - `SHOW_REGISTRATION_BUTTON=false`로 Gitea 자체 공개 가입 버튼을 숨긴다. - `oauth2_client.ENABLE_AUTO_REGISTRATION=true`, `USERNAME=preferred_username`, `OPENID_CONNECT_SCOPES="profile email"`로 OIDC 최초 로그인 계정을 생성한다. - baseline의 `ENABLE_PASSWORD_SIGNIN_FORM=true`를 유지해 Keycloak 장애 시에도 로컬 비상 관리자가 로그인할 수 있게 한다. `ACCOUNT_LINKING=login`은 이메일이 같은 기존 계정을 자동 병합하지 않는다. 사용자가 기존 Gitea 자격 증명으로 한 번 더 확인해야 연결되므로, 이메일 일치만으로 계정을 탈취하는 위험을 줄인다. ## 의존성과 트래픽 - `gitea`와 `platform-data` namespace를 먼저 적용한다. - 이 서비스를 적용하기 전에 `/srv/k3s/ssd/gitea`를 준비하고 `gitea-local-pv` 기반 구성을 적용한다. `gitea-data` Claim은 `ssd-local-gitea-retain`을 통해 해당 PV에 바인딩되며 `50Gi`를 요청한다. - 외부 Database endpoint는 `platform-postgres-rw.platform-data.svc.cluster.local:5432`다. - Host Nginx에서 공개 TLS를 종료한다. Traefik은 HTTP를 받아 `gitea-http:3000`으로 전달하며, 이 Ingress에는 의도적으로 TLS 섹션이 없다. - OIDC profile의 Gitea 서버가 discovery와 token endpoint에 접근할 때도 공개 issuer `https://id.learn.hyeonworks.com/realms/hyeonworks`를 사용한다. 홈 라우터의 NAT loopback에 의존하지 않도록 Pod의 `hostAliases`는 이 이름만 노드 `192.168.0.107`로 해석하고, 전용 NetworkPolicy가 해당 `/32`의 TCP 443만 허용한다. 연결은 Host Nginx TLS와 Traefik을 그대로 통과한다. - Gitea SSH와 Git LFS는 비활성화한다. Chart `12.7.0`은 항상 SSH Service를 렌더링하므로 baseline 루트는 inline patch, OIDC profile은 `patches/delete-ssh-service.yaml`로 Helm 렌더링 뒤 `gitea-ssh`를 삭제한다. - Actions와 Package Registry는 첫 배포에서 껐다가 2026-11-07 소유자 결정으로 서버에서 켰다(`[actions] ENABLED=true`, `[packages] ENABLED=true`, `DISABLED_REPO_UNITS=""`). 꺼져 있을 때 만든 repository에는 두 unit이 없으므로 기존 repository는 모두 `has_actions=false`, `has_packages=false`로 남고, 소유자가 repository 설정에서 켜야 workflow가 돌거나 repository에 패키지 탭이 생긴다. 새로 만드는 repository는 Gitea 기본값(`DEFAULT_REPO_UNITS`)에 따라 두 unit이 켜진 채 만들어진다. 아래 「Actions와 Package Registry」를 따른다. - 공통 egress는 클러스터 DNS, 플랫폼 PostgreSQL Pod 및 공개 IPv4 HTTPS 대상으로 제한한다. OIDC profile만 Host Nginx 노드 `/32`의 TCP 443을 추가한다. 내부 HTTPS, SMTP, SSH remote 및 사설 네트워크 webhook을 사용하려면 향후 NetworkPolicy를 명시적으로 변경해야 한다. Actions runner와 Maven 클라이언트는 기존 Host Nginx → Traefik HTTPS 경로로 Gitea에 들어오기만 하므로 egress는 바꾸지 않는다. ## Actions와 Package Registry ### Actions runner는 Gitea Pod가 아니라 desktop 호스트의 Docker 컨테이너다. 이미지, 설정, 등록과 되돌리기는 [Gitea Actions runner](../../infrastructure/ci/gitea-runner/README.md)에 있다. 서버 쪽 설정은 Gitea 기본값을 쓴다. job log와 artifact는 `/data` 아래 (`actions_log`, `actions_artifacts`)에 저장되고 log는 365일, artifact는 90일 보관한다. ### 저장 위치와 용량 | 항목 | 값 | | --- | --- | | 패키지 blob | `APP_DATA_PATH`(`/data`) 아래 `/data/packages` | | chunked upload 임시 위치 | `/data/tmp/package-upload` | | 호스트 경로 | `gitea-local-pv`의 `/srv/k3s/ssd/gitea` (root SSD) | | PVC 요청 | `50Gi` | Local PV는 PVC 크기를 강제하지 않는다. 실제 상한은 root SSD의 남은 공간이고, 이 공간을 desktop 호스트, Actions runner의 Docker 볼륨과 함께 쓴다(2026-11-07 기준 228G 중 여유 33G, Gitea `/data` 사용량 약 267M). 소유자별 상한 (`LIMIT_TOTAL_OWNER_SIZE`)과 형식별 상한(`LIMIT_SIZE_MAVEN`)은 Gitea 기본값인 무제한(`-1`)이다. Host Nginx의 `git.learn.hyeonworks.com` 요청 본문 상한은 `512m`이라 이보다 큰 파일은 올라가지 않는다. ### 정리 - 같은 파일은 blob 하나로 저장된다. 패키지를 지우면 참조만 지워지고, 참조가 없는 blob은 cron `cleanup_packages`(기본: 매일 자정, `OLDER_THAN=24h`)가 지운다. - 오래된 버전은 패키지 소유자(사용자·조직)가 설정 → Packages → Cleanup rules에서 지운다. Maven SNAPSHOT은 형식 `maven`, 「Remove versions matching」에 `.+-SNAPSHOT`, 「Keep the most recent」에 남길 개수를 두는 규칙을 권한다. 규칙을 켜기 전에 preview로 지워질 버전을 확인한다. 2026-11-07 현재 규칙은 없다. - 같은 이름·버전의 Maven 패키지는 다시 올릴 수 없다. 먼저 그 버전을 지워야 한다. ### Maven 배포와 조회 권한 - 저장소 URL: `https://git.learn.hyeonworks.com/api/packages/{owner}/maven` - 조회: 사용자 소유 패키지는 그 사용자가 public이면 공개이고, 아니면 그 사용자만 읽는다. `donghyeon.kang`은 public이고 `REQUIRE_SIGNIN_VIEW`를 켜지 않았으므로 이 사용자의 패키지는 인증 없이 받을 수 있다. 조직 패키지는 조직이 public이면 공개, 아니면 조직 member만 읽는다. - 배포: 사용자 패키지는 소유자만, 조직 패키지는 packages 쓰기 권한이 있는 team member만 올린다. Maven·Gradle은 personal access token을 `Authorization: token ` header로 보낸다. token 권한은 package `Read & Write`(`write:package`)가 필요하고, 비공개 패키지를 받기만 할 때는 `Read`(`read:package`)면 된다. - Actions job 안에서 배포할 때는 token을 repository나 사용자 Actions secret으로 넘긴다. workflow 파일과 log에 token을 쓰지 않는다. 출처: [Package Registry](https://docs.gitea.com/1.27/usage/packages/overview), [Maven](https://docs.gitea.com/1.27/usage/packages/maven), [Storage](https://docs.gitea.com/1.27/usage/packages/storage), [Config cheat sheet](https://docs.gitea.com/1.27/administration/config-cheat-sheet). ## 선언형 브랜딩 브랜딩은 Gitea 공식 custom path와 Chart의 volume 확장 필드만 사용한다. Chart 템플릿과 Gitea 전체 페이지 템플릿은 복제하거나 수정하지 않는다. ```text branding/ ├── public/assets/ │ ├── css/hyeonworks.css │ └── img/ │ ├── logo.svg │ └── favicon.svg └── templates/custom/ ├── header.tmpl └── extra_links.tmpl ``` `branding/kustomization.yaml`의 `configMapGenerator`가 자산과 템플릿 ConfigMap을 각각 생성하고 `profiles/oidc/kustomization.yaml`만 이 구성요소를 포함한다. 이름 suffix hash를 끄지 않았으므로 파일 내용이 바뀌면 이름도 바뀌고, Kustomize가 Deployment의 ConfigMap 참조를 같은 해시 이름으로 치환한다. `profiles/oidc/values/oidc.yaml`은 공식 Chart 확장 지점을 다음과 같이 사용한다. - 자산 ConfigMap을 `/data/gitea/public/assets`에 마운트한다. - 템플릿 ConfigMap을 `/data/gitea/templates/custom`에 마운트한다. - 두 volume은 rootless Gitea 주 컨테이너에만 `readOnly: true`로 마운트하며, init container에는 추가하지 않는다. `header.tmpl`은 같은 origin의 CSS와 모바일 브라우저 색상만 추가한다. `extra_links.tmpl`은 실제 Gitea 내부 경로인 `/explore/organizations`만 연결한다. 존재하지 않는 Learning 또는 Identity 서비스 링크는 미리 만들지 않는다. 전체 `home.tmpl`은 덮어쓰지 않아 Gitea 업그레이드 때 template drift 범위를 줄인다. Gitea는 custom template을 시작할 때 읽으므로 변경 적용에는 Pod 재시작이 필요하다. SVG 원본만 저장소에서 관리한다. Gitea가 참조하는 Open Graph, Apple touch icon 및 구형 브라우저용 PNG는 검증된 변환 절차를 추가하기 전까지 업스트림 기본 자산을 사용한다. - [Gitea 1.27 커스터마이징 공식 문서](https://docs.gitea.com/administration/customizing-gitea) - [Gitea Chart 12.7.0 공식 values](https://gitea.com/gitea/helm-chart/src/tag/v12.7.0/values.yaml) ## Secret 계약 credential Secret 매니페스트나 credential 값은 이 저장소에 두지 않는다. `gitea-admin`과 `gitea-db-credentials`는 baseline Deployment 최초 시작 전에, `gitea-keycloak-oidc`는 OIDC-enabled Deployment rollout 전에 `gitea` namespace에 있어야 한다. ### `gitea-admin` | 속성 | 필수 값 | | --- | --- | | Kubernetes 유형 | `kubernetes.io/basic-auth` | | `username` | 최초 로컬 비상 관리자 username | | `password` | 강력한 일회용 관리자 비밀번호 | Chart는 `initialOnlyRequireReset`을 사용하므로 최초 로그인 때 초기 비밀번호를 변경해야 하며 이후에는 조정하지 않는다. ### `gitea-db-credentials` | 속성 | 필수 값 | | --- | --- | | Kubernetes 유형 | `kubernetes.io/basic-auth` | | `username` | `gitea` | | `password` | PostgreSQL `gitea` Role에 할당한 비밀번호 | Kubernetes에서는 namespace를 넘어 Secret을 참조할 수 없다. `platform-data`에 있는 같은 이름의 Secret은 CloudNativePG/bootstrap 사본이다. `gitea` namespace의 Secret은 동일한 Database credential을 담아야 하며 Chart가 이 사본을 참조한다. ### `gitea-keycloak-oidc` | 속성 | 필수 값 | | --- | --- | | Kubernetes 유형 | `Opaque` | | `key` | `gitea` | | `secret` | Keycloak이 생성한 confidential client secret | `scripts/bootstrap/configure-keycloak-gitea-oidc.sh`가 Keycloak Admin REST API로 정확한 callback URI를 가진 client를 생성하거나 갱신하고 이 Secret을 만든다. 공식 Chart의 `gitea.oauth[].existingSecret`이 `key`와 `secret`을 환경 변수로만 초기화 컨테이너에 전달하고, 인증 소스 이름 `keycloak`을 반복 실행 시 갱신한다. Secret payload는 values, 렌더 결과 또는 Git에 포함되지 않는다. 업스트림 Chart는 credential이 아닌 초기화 스크립트와 inline 설정이 담긴 Opaque Secret도 렌더링한다. 이 생성 리소스들은 고정된 Chart의 일부이며 위 세 credential 계약의 값은 포함하지 않는다. ## 렌더링과 검사 Helm은 `PATH`에 있어야 하지만 릴리스를 직접 설치하는 데 사용하지 않는다. 플랫폼 저장소 루트에서 고정 Chart SHA를 확인하는 검증기로 렌더링한다. ```sh PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \ bash scripts/validate/render-phase1.sh ``` 검증기는 `gitea.yaml` baseline과 `gitea-oidc.yaml` 목표 상태를 모두 렌더한다. 두 결과에는 각각 Gitea Deployment 하나, `gitea-http`, `gitea-data`, Traefik Ingress가 있어야 하고 `gitea-ssh`, NodePort, LoadBalancer와 내부 TLS는 없어야 한다. 두 Deployment 모두 `gitea-admin`, `gitea-db-credentials`를 참조만 하고 생성하지 않는다. baseline은 `gitea-keycloak-oidc`, ID host alias, Keycloak 전용 NetworkPolicy, 브랜딩 ConfigMap과 외부 인증 전용 가입 설정이 없어야 한다. 반대로 OIDC 산출물은 `gitea-keycloak-oidc`를 값 노출 없이 참조하고 다음을 모두 만족해야 한다. - 두 브랜딩 ConfigMap 이름에 content hash가 있고 Deployment 참조와 일치한다. - `/data/gitea/public/assets`와 `/data/gitea/templates/custom` 마운트는 read-only다. - inline 설정에 외부 인증 전용 가입, OIDC 자동 계정 생성, `ACCOUNT_LINKING=login`, 로컬 비밀번호 로그인 유지가 모두 렌더링된다. - OAuth 인증 소스 이름은 callback URI의 경로와 같은 `keycloak`이고 discovery issuer는 `https://id.learn.hyeonworks.com/realms/hyeonworks`다. ## Keycloak OIDC 안전 적용 Host Nginx의 Keycloak discovery가 실제 JSON issuer를 반환하고 위 세 Secret 계약이 준비된 뒤 다음 전용 진입점으로 적용한다. 1. Host Nginx의 `id.learn.hyeonworks.com` 정적 hold를 Keycloak proxy 후보로 전환한다. 2. public discovery JSON의 `issuer`가 `https://id.learn.hyeonworks.com/realms/hyeonworks`와 정확히 같은지 확인한다. 3. 다음 전용 스크립트로 OIDC 목표 상태와 브랜딩을 함께 적용한다. ```sh PLATFORM_HELM_BIN=/home/donghyeon/.local/bin/helm \ bash scripts/bootstrap/apply-gitea-oidc.sh --execute ``` 스크립트는 public discovery와 Secret의 type·key 이름만 먼저 확인하고, 고정 Chart SHA 검증 결과 중 `gitea-oidc.yaml` 하나만 적용한다. 이후 Deployment·EndpointSlice, 활성 `keycloak` OAuth2 source, 외부 인증 전용 가입 정책, OIDC authorization-code redirect와 브랜딩 자산 SHA-256을 검증한다. Secret 값, bearer token과 OIDC state가 포함된 전체 Location은 출력하지 않는다. 2026-07-23 실제 적용에서는 manifest SHA-256 `d25a757...a157`의 rollout과 위 자동 검사를 모두 통과했다. 이 redirect 검사는 realm 사용자의 실제 브라우저 login/callback/logout 시험을 대신하지 않는다. self-registration은 비활성이므로 named 관리자와 MFA를 준비한 뒤 시험 사용자를 별도로 생성한다. 로컬 비상 관리자 실제 로그인과 Pod 재시작 뒤 OAuth source·정책·브랜딩 지속성도 별도로 확인한다. 기존 Gitea에 `apply-phase1-gitea.sh`를 다시 실행해 OIDC 상태를 적용하거나 복구하지 않는다.