GitLab 프로젝트 구조 정책¶

0. 전제¶

GitLab Project 경로와 명명 기준을 먼저 정의함.

PROJECT_NAME / SERVICE_PREFIX / SERVICE_NAME 구조를 전제로 함

운영 변수 기준:

변수	의미
`PROJECT_NAME`	최상위 제품/서비스 단위이며 GitLab 최상위 Group 및 Release Storage Bucket 기준
`SERVICE_PREFIX`	`PROJECT_NAME` 하위의 고정 서비스 분류 경로이며 GitLab Subgroup 및 Release Storage 중간 Prefix 기준
`SERVICE_NAME`	실제 실행/배포 대상 서비스명이며 GitLab Project 이름 및 runtime app name 기준

경로 매핑:

GitLab path:
{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}

Release Storage:
s3://{PROJECT_NAME}/{SERVICE_PREFIX}/{SERVICE_NAME}/{RELEASE_ENV}/current/{RELEASE_ENV}.json

Runtime:
/var/www/{SERVICE_NAME}

운영 기준:

PROJECT_NAME 은 GitLab 최상위 Group 이름과 Release Storage Bucket 이름 기준으로 사용함
SERVICE_PREFIX 는 PROJECT_NAME 하위의 고정 서비스 분류 경로로 사용함
SERVICE_PREFIX 는 일반적으로 frontend, backend, db, infra 같은 GitLab Subgroup 이름과 일치시킴
SERVICE_NAME 은 실제 GitLab Project 이름, PM2 app name, 운영 서버 runtime directory 이름으로 사용함
GitLab UI 의 Project 개념과 문서 변수 PROJECT_NAME 은 의미가 다르므로 구분해서 사용함

1. 개요¶

본 정책은 다음을 보장하기 위해 정의됨:

프로젝트 구조 일관성 유지
서비스 단위 명확화
Release Storage / Polling Deploy 구조와 일관된 명명 기준 확보

2. 구조 개념 (운영 기준)¶

본 조직은 GitLab 기본 구조(Group / Subgroup / Project)를
다음과 같은 운영 모델로 사용함.

PROJECT_NAME → SERVICE_PREFIX → SERVICE_NAME

2.1 PROJECT_NAME¶

최상위 제품/서비스 단위
GitLab 최상위 Group 이름 기준
Release Storage Bucket 이름 기준
여러 실행 서비스 또는 하위 Project 를 묶는 운영 단위

2.2 SERVICE_PREFIX¶

PROJECT_NAME 내부의 고정 서비스 분류 경로
GitLab Subgroup 이름 기준
Release Storage 중간 Object Prefix 기준
일반적으로 frontend, backend, db, infra 같은 값을 사용함

운영 기준:

SERVICE_PREFIX 는 GitLab repository path 에서 PROJECT_NAME 과 SERVICE_NAME 사이의 경로와 일치시킴
SERVICE_PREFIX 는 Release Storage object path 에서 PROJECT_NAME 과 SERVICE_NAME 사이의 경로와 일치시킴
SERVICE_PREFIX 는 실행 서비스명이나 GitLab Project 이름을 포함하지 않음
실제 실행/배포 대상 이름은 SERVICE_NAME 으로 관리함

2.3 SERVICE_NAME¶

실제 실행/배포 대상 서비스명
GitLab Project 이름
운영 서버 runtime root directory 이름
PM2 app name

운영 기준:

SERVICE_NAME 은 .ops/cd/env/.service.env 의 SERVICE_NAME 값과 일치시킴

3. 구조 분리 원칙¶

본 구조는 다음 두 영역을 명확히 분리함:

[조직 영역]
company
└── frontend / backend / db ...

[서비스 영역]
{PROJECT_NAME}
└── {SERVICE_PREFIX} / frontend / backend / db ...

4. 기본 구조¶

{PROJECT_NAME}
└── {SERVICE_PREFIX}
    └── {SERVICE_NAME}

5. 구조 설계 원칙¶

5.1 PROJECT_NAME 설계 기준¶

제품/서비스 단위로 최상위 Group 생성
하나의 제품/서비스는 하나의 최상위 Group 으로 유지

5.2 SERVICE_PREFIX 설계 기준¶

모든 Project 는 반드시 SERVICE_PREFIX 하위에 위치
SERVICE_PREFIX 는 GitLab Subgroup 이름으로 사용함
SERVICE_PREFIX 는 Release Storage object path 의 중간 prefix 로 사용함

5.3 SERVICE_NAME 설계 기준¶

GitLab Project 이름은 SERVICE_NAME 기준으로 사용함
하나의 프로젝트 = 하나의 실행 단위
서비스 단위 기준 유지
Project 내부 CI/CD 및 CD runtime 은 .ops 기준으로 관리함

6. 프로젝트 생성 정책¶

6.1 생성 기준¶

반드시 PROJECT_NAME / SERVICE_PREFIX 하위에 생성함

6.2 생성 권한¶

운영 Project 생성은 Maintainer 이상 권한으로 수행함
Developer 권한 사용자는 운영 Project 생성 권한을 가지지 않음

7. 네이밍 규칙¶

kebab-case 사용
서비스 기준 명명
의미 없는 이름 사용 금지
GitLab Project 이름은 가능하면 실제 runtime SERVICE_NAME 과 일치시킴

example.com
admin.example.com
auth-service
payment-api
gateway-config