목적: prego-saas-app 레포에서 발생한 이벤트가 prego-docker 레포의 GitHub Actions를 트리거하고, 해당 시점의 custom app(커밋)을 반영해 Docker 이미지가 빌드·푸시되는 전 과정을 단계별로 정리한다. 코드 생성 없음 — 흐름·역할·입출력·Secrets·전제만 명세.
관련 레포: Pregoi/prego-saas-app(이벤트 발생), Pregoi/prego-docker(이미지 빌드).
현재 구현과의 차이: 본 문서는 app_sha 기반 동적 apps.json 설계(원안)를 기술한다. 현재 prego-docker는 커밋된 apps.json에 prego-saas-app 태그(예: v1.0.0)를 두고, dispatch 시 동적 생성 없이 해당 파일을 Base64로 전달한다. prego-saas-app 쪽에서 새 버전 배포 시 태그를 push한 뒤, prego-docker의 apps.json에서 해당 태그로 수정·커밋하거나, dispatch는 이미지 태그(예: pregoapp-<sha>)만 전달하는 역할. 상세: prego-docker-implementation-plan.md §4·§5.
1. 전체 흐름 요약
[prego-saas-app] [GitHub] [prego-docker]
│ │ │
│ push/tag 발생 │ │
│ (main, staging, develop, v*.*.*) │ │
├──────────────────────────────────► │
│ 워크플로 실행 │ │
│ (notify-image-rebuild) │ │
│ │ repository_dispatch │
│ POST /repos/.../dispatches │ event_type: custom_app_updated │
│ client_payload: { app_sha, tag } ├────────────────────────────────►│
│ │ │
│ │ build-and-push 워크플로 실행 │
│ │ • app_sha로 apps.json에 │
│ │ prego-saas-app 브랜치 고정 │
│ │ • Dockerfile 빌드(APPS_JSON) │
│ │ • (필요 시) clone_token으로 │
│ │ private 레포 clone │
│ │ • 이미지 푸시 (태그·digest) │
│ │ │
이벤트 발생처: prego-saas-app 레포의 push 또는 tag.
연결 고리: GitHub repository_dispatch API — prego-saas-app 워크플로가 prego-docker 레포로 “custom_app_updated” 이벤트를 보냄.
이미지 빌드처: prego-docker 레포의 GitHub Actions가 해당 이벤트를 받아, payload에 담긴 app_sha(커밋) 로 custom app 버전을 고정한 뒤 Docker 이미지를 빌드·푸시.
2. 단계별 상세
2.1 단계 1: prego-saas-app에서 이벤트 발생
항목
내용
트리거
prego-saas-app 레포에 대한 push 또는 tag push.
대상 브랜치/태그
기획 상 main, staging, develop 브랜치 push, 또는 v..*** 형식의 태그 push. (구현 시 워크플로 on.push / on.tags 에 정의.)
의미
“custom app(prego-saas-app) 코드가 이 시점으로 갱신되었으니, 이 커밋을 포함한 런타임 이미지를 만들어라”는 신호.
선택 정책: 특정 브랜치만 이미지화하거나, 태그만 이미지화하도록 트리거를 줄일 수 있음. 기획 기본값은 main/staging/develop + 태그.
2.2 단계 2: prego-saas-app 워크플로 실행 (dispatch 전송)
항목
내용
실행 위치
prego-saas-app 레포의 GitHub Actions.
워크플로 역할
위 push/tag 이벤트를 받아 prego-docker 레포로 repository_dispatch API를 한 번 호출.
API
POST https://api.github.com/repos/{owner}/{repo}/dispatches (대상: Pregoi/prego-docker).
필수 인증
GitHub Personal Access Token(PAT). prego-saas-app 레포 Secrets에 저장(예: PREGODOCKER_DISPATCH_PAT). prego-docker 레포에 대한 repo 권한 필요(public 레포여도 dispatch 호출을 위해 권한 권장).
“이제 이 app_sha(커밋)를 사용해 custom app을 포함한 이미지를 빌드한다.”
prego-docker 쪽에서는 push/tag가 아니라 “다른 레포에서 보낸 dispatch”이므로, 빌드 시 사용할 앱 목록을 레포 기본 apps.json이 아니라, app_sha를 반영한 목록으로 만들어야 함.
2.4 단계 4: custom app 버전 고정(apps.json 생성)
항목
내용
목적
Dockerfile이 bench init 시 사용할 apps.json에 prego-saas-app을 특정 커밋(app_sha) 으로 고정.
방식
repository_dispatch 분기에서만: (1) client_payload.app_sha 로 prego-saas-app 항목을 branch: "${APP_SHA}" 형태로 설정. (Git에서 branch 필드에 commit SHA를 지정하면 해당 커밋을 checkout함.) (2) ERPNext·HRMS는 고정 브랜치(예: version-15) 유지. (3) 이 내용을 apps.json으로 저장한 뒤, Base64 등으로 인코딩해 Docker 빌드 인자(예: APPS_JSON_BASE64)로 전달.
일반 push 시
prego-docker 자체 push/tag 시에는 레포에 있는 기본 apps.json을 그대로 Base64 인코딩해 빌드 인자로 넘김. (prego-saas-app은 기본 apps.json에 branch: main 등으로 정의.)
정리: “이벤트로 custom app을 가져간다”는 것은 dispatch 시점에 app_sha로 apps.json을 동적 생성하고, 그 내용을 Docker 빌드에 넘겨 해당 커밋의 prego-saas-app만 이미지에 포함시키는 것이다.
2.5 단계 5: Docker 빌드에서 custom app 반영
항목
내용
Dockerfile
frappe_docker custom 패턴: APPS_JSON_BASE64(또는 동일 역할 인자)를 받아 /opt/frappe/apps.json 등으로 복원한 뒤, bench init 시 이 경로를 사용해 앱 설치(ERPNext, HRMS, prego-saas-app).
clone 시점
빌드 중 bench init → bench get-app 등이 prego-saas-app 레포를 clone. 이때 apps.json에 넣은 branch(SHA) 로 checkout 되므로, 이벤트가 발생한 그 커밋이 이미지에 들어감.
Private 레포
prego-saas-app이 private이면 clone 시 인증 필요. prego-docker 레포 Secrets에 clone용 토큰(예: PREGO_SAAS_APP_CLONE_TOKEN)을 두고, Dockerfile에서 URL을 https://<token>@github.com/... 형태로 치환하거나, build secret으로 전달. (기획: build secret 사용 시 Dockerfile은 RUN --mount=type=secret,id=clone_token 등으로 받아 URL만 치환.)
Public 레포
clone 토큰 없이 그대로 clone 가능.
결과: 빌드된 이미지 안에는 이벤트 발생 시점의 prego-saas-app 코드가 포함됨.
2.6 단계 6: 이미지 태그·푸시·digest 출력
항목
내용
태그
client_payload.tag 사용(예: pregoapp-abc1234, v1.2.3). 추가로 latest 등 고정 태그 병행 가능.
푸시
Docker Hub 등 레지스트리에 푸시. (prego-docker Secrets: DOCKERHUB_USERNAME, DOCKERHUB_TOKEN.)
digest
빌드 결과 이미지 digest를 워크플로 출력으로 남겨, 운영·승격(Staging→Production) 시 digest 고정 배포에 사용.
3. 역할·Secret 정리
구분
레포
역할
Secret(예시)
이벤트 발생
prego-saas-app
push/tag 시 repository_dispatch 전송
PREGODOCKER_DISPATCH_PAT (prego-docker에 dispatch 보낼 PAT)
