Files
platform-core/services/gitea
DongHyeonka a92e6b854b docs(gitea): record the Actions and package registry rollout
The Gitea README still said Actions and the package registry are
disabled on first deployment, and had no guidance for either.

Replace that decision with the 2026-11-07 state, add where packages
are stored and how much space they really have (a local PV does not
enforce the 50Gi request), the cleanup rules to use for Maven
SNAPSHOTs, and who may publish and read Maven packages. Record the
applied manifest SHA-256 and link the runner guide from the root
README.

Verification: statements checked against the Gitea 1.27 docs and
source (routers/api/packages/maven, modules/web/router.go), the live
app.ini, and API responses after the rollout.
2026-11-07 18:36:55 +09:00
..

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에 있다. 서버 쪽 설정은 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 <token> header로 보낸다. token 권한은 package Read & Write(write:package)가 필요하고, 비공개 패키지를 받기만 할 때는 Read(read:package)면 된다.
  • Actions job 안에서 배포할 때는 token을 repository나 사용자 Actions secret으로 넘긴다. workflow 파일과 log에 token을 쓰지 않는다.

출처: Package Registry, Maven, Storage, Config cheat sheet.

선언형 브랜딩

브랜딩은 Gitea 공식 custom path와 Chart의 volume 확장 필드만 사용한다. Chart 템플릿과 Gitea 전체 페이지 템플릿은 복제하거나 수정하지 않는다.

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는 검증된 변환 절차를 추가하기 전까지 업스트림 기본 자산을 사용한다.

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를 확인하는 검증기로 렌더링한다.

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 목표 상태와 브랜딩을 함께 적용한다.
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 상태를 적용하거나 복구하지 않는다.