DOCS/02_Architecture/51123_github_org_repo_bootstrap_runbook.md

tags

tags
infra github org repository bootstrap runbook 51123

51123 GitHub Org Repo Bootstrap Runbook

상위 원칙

• Infra Project Identity
• Core Infrastructure Principles
• Operational Guardrails
• 공통 작성 원칙: 0_VALUE Writing Principles

관련 문서

• Infrastructure Project Structure
• 51123 -> 내부 NAS 동기화 점검 런북
• 260307 infra_scripts 원격 미존재 푸시실패 및 조직레포 생성 조치
• 260307 수정 레포 일괄 푸시 및 infra/scripts 신규 레포 연결

목적

• 51123 서버에서 GitHub org 기준 새 프로젝트 루트와 다중 저장소를 같은 절차로 만든다.
• 이 문서는 사건 기록이 아니라, 운영자가 다시 실행할 수 있는 고정 절차를 남기는 런북이다.

적용 범위

• 실행 서버: 51123
• 기준 경로: /home/admin/<org>
• 원격 대상: GitHub organization
• 기본 저장소 묶음:
  • DOCS
  • DATA
  • web
  • admin
  • api

SSOT 기준값

• 작업 루트: /home/admin
• 공통 런타임 기준 파일:
  • /home/admin/workspace-config/runtime.env
  • /home/admin/workspace-config/secrets.env
• Git 사용자 기준:
  • git config --global user.name
  • git config --global user.email
• GitHub 인증 기준:
  • ~/.git-credentials에 저장된 github.com 자격증명
  • gh CLI는 설치되어 있어야 한다.

사전 확인

1. 기본 도구와 자격 확인

which gh
git config --global --get user.name
git config --global --get user.email
python3 - <<'PY'
from pathlib import Path
text = Path('/home/admin/.git-credentials').read_text() if Path('/home/admin/.git-credentials').exists() else ''
print('github.com credential found' if 'github.com' in text else 'github.com credential missing')
PY

확인 기준:

• gh 경로가 보여야 한다.
• Git 전역 사용자명이 설정되어 있어야 한다.
• github.com credential found가 나와야 한다.

2. org와 기존 레포 상태 확인

python3 - <<'PY'
from pathlib import Path
from urllib.parse import urlparse
import os, subprocess

org = 'xvaluelab'
token = None
for line in Path('/home/admin/.git-credentials').read_text().splitlines():
    if 'github.com' in line:
        token = urlparse(line.strip()).password
        break
env = os.environ.copy()
env['GH_TOKEN'] = token
subprocess.run(['gh', 'api', f'/orgs/{org}/repos?per_page=100'], env=env, check=True)
print('org access ok')
PY

확인 기준:

• org access ok가 보여야 한다.
• 실패하면 토큰 스코프나 org 접근 권한을 먼저 해결한다.

생성 절차

1. 프로젝트 루트 생성

export ORG_NAME=xvaluelab
export PROJECT_ROOT=/home/admin/$ORG_NAME

mkdir -p "$PROJECT_ROOT"
mkdir -p "$PROJECT_ROOT/DATA"
mkdir -p "$PROJECT_ROOT/apps/web"
mkdir -p "$PROJECT_ROOT/apps/admin"
mkdir -p "$PROJECT_ROOT/apps/api"

설명:

• 프로젝트 루트는 /home/admin/<org>로 고정한다.
• DOCS, DATA, apps/* 경계를 처음부터 분리한다.

2. DOCS 처리

git clone https://github.com/$ORG_NAME/DOCS.git "$PROJECT_ROOT/DOCS"

설명:

• 사용자가 이미 DOCS 원격을 만든 경우 먼저 clone한다.
• 빈 저장소면 초기 구조를 채운 뒤 커밋/푸시한다.

3. 로컬 초기 파일 정리

최소 기준:

• DOCS: 원칙, 구조, 제품, journey 인덱스
• DATA: README, .gitignore
• apps/web: README, .gitignore
• apps/admin: README, .gitignore
• apps/api: README, .gitignore

설명:

• 공통 비밀은 프로젝트 .env.local에 중복 저장하지 않는다.
• 공통 값은 workspace-config를 SSOT로 유지하고, 프로젝트 로컬에는 오버라이드만 둔다.

4. 원격 저장소 생성

python3 - <<'PY'
from pathlib import Path
from urllib.parse import urlparse
import os, subprocess

org = 'xvaluelab'
repos = ['DATA', 'web', 'admin', 'api']
token = None
for line in Path('/home/admin/.git-credentials').read_text().splitlines():
    if 'github.com' in line:
        token = urlparse(line.strip()).password
        break
env = os.environ.copy()
env['GH_TOKEN'] = token

for name in repos:
    subprocess.run([
        'gh', 'api', '-X', 'POST', f'/orgs/{org}/repos',
        '-f', f'name={name}',
        '-f', 'private=true'
    ], env=env, check=False)
PY

설명:

• 이미 있는 레포는 422 already exists가 나올 수 있으므로 존재 여부 확인 후 넘어간다.
• private 기본값을 사용하고, 공개 여부는 별도 판단 후 바꾼다.

5. 각 저장소 초기화와 최초 푸시

for d in \
  /home/admin/xvaluelab/DATA \
  /home/admin/xvaluelab/apps/web \
  /home/admin/xvaluelab/apps/admin \
  /home/admin/xvaluelab/apps/api
do
  git -C "$d" init -b main
done

원격 연결 기준:

• DATA -> https://github.com/<org>/DATA.git
• apps/web -> https://github.com/<org>/web.git
• apps/admin -> https://github.com/<org>/admin.git
• apps/api -> https://github.com/<org>/api.git

최초 커밋/푸시 기준:

git -C /home/admin/xvaluelab/DATA add .
git -C /home/admin/xvaluelab/DATA commit -m "Initialize repository structure"
git -C /home/admin/xvaluelab/DATA push -u origin main

설명:

• 각 저장소 루트에서 같은 패턴으로 add -> commit -> push를 반복한다.
• DOCS도 같은 방식이지만, clone한 저장소에서 수행한다.

검증 절차

1. 로컬 추적 상태 확인

for d in \
  /home/admin/xvaluelab/DOCS \
  /home/admin/xvaluelab/DATA \
  /home/admin/xvaluelab/apps/web \
  /home/admin/xvaluelab/apps/admin \
  /home/admin/xvaluelab/apps/api
do
  echo "[$d]"
  git -C "$d" status -sb
  git -C "$d" remote -v
done

확인 기준:

• 각 저장소가 main...origin/main 추적 상태여야 한다.
• origin이 GitHub org 레포를 가리켜야 한다.

2. 원격 생성 결과 확인

python3 - <<'PY'
from pathlib import Path
from urllib.parse import urlparse
import os, subprocess

org = 'xvaluelab'
token = None
for line in Path('/home/admin/.git-credentials').read_text().splitlines():
    if 'github.com' in line:
        token = urlparse(line.strip()).password
        break
env = os.environ.copy()
env['GH_TOKEN'] = token
subprocess.run(['gh', 'api', f'/orgs/{org}/repos?per_page=100'], env=env, check=True)
PY

확인 기준:

• DOCS, DATA, web, admin, api가 모두 보여야 한다.

성공 판정 규칙

A. 구조 생성 성공

• /home/admin/<org> 아래에 DOCS, DATA, apps/web, apps/admin, apps/api가 존재한다.

B. GitHub 생성 성공

• 대상 org에 필요한 레포가 모두 생성된다.

C. 최초 푸시 성공

• 각 저장소 루트가 main...origin/main 추적 상태다.
• 원격 기본 브랜치에 초기 커밋이 보인다.

점검 결과를 어디에 남길지

• 반복 절차 자체는 이 런북을 SSOT로 유지한다.
• 특정 날짜의 실제 실행 기록은 아래 중 하나에 남긴다.
  • 실패/차단/권한 이슈가 있으면 journey/troubleshooting/
  • 문제 없이 끝났으면 journey/worklog/

이 런북이 다루지 않는 것

• 프로젝트별 문서 내용 설계
• 앱 코드 구현
• GitHub 팀 권한 설계
• 실제 secret 발급과 노출 정책

한 줄 결론

• 이 런북은 51123 서버에서 GitHub org 기준 새 프로젝트 루트와 다중 저장소를 같은 절차로 반복 생성하고 최초 푸시하는 표준 절차다.