English {#english}

Trigger prego-docker image build when prego_saas is pushed (or tagged). prego_saas needs PREGODOCKER_DISPATCH_PAT to call repository_dispatch; prego-docker needs DOCKERHUB_* and (if prego_saas is private) PREGO_SAAS_APP_CLONE_TOKEN. prego-docker workflow listens for custom_app_updated. Full details: see Korean section below.

---

한국어 {#korean}

prego_saas → prego-docker 이미지 재빌드 트리거 설정

목적: prego_saas 레포에 push(또는 tag) 시 prego-docker의 이미지 빌드 워크플로가 자동 실행되도록 설정한다.

누가 어떤 Secret을 쓰나요?

레포	Secret 이름	용도	언제 필요
prego_saas	PREGODOCKER_DISPATCH_PAT	prego-docker 레포로 repository_dispatch API 호출 시 인증	항상 (자동 재빌드 쓰려면)
prego-docker	DOCKERHUB_USERNAME / DOCKERHUB_TOKEN	Docker Hub에 이미지 푸시	항상
prego-docker	PREGO_SAAS_APP_CLONE_TOKEN	빌드 중 prego_saas(private) 레포 git clone 시 인증	prego_saas가 private일 때만

• prego_saas → prego-docker: prego_saas가 “prego-docker야, 빌드 돌려” 하고 API를 호출하는 쪽이므로, 호출하는 쪽(prego_saas) 에 PAT가 필요하다. prego-docker는 그냥 GitHub가 repository_dispatch 이벤트를 넘겨주기만 하면 되고, prego-docker가 prego_saas를 “호출”하는 구조가 아니다.
• prego-docker → prego_saas: 빌드 시 apps.json에 ERPNext·HRMS·prego_saas(태그)이 모두 들어 있으며, bench init 한 번으로 설치된다. prego_saas가 private이면 clone 시 인증이 필요하므로 prego-docker 레포에 PREGO_SAAS_APP_CLONE_TOKEN을 둔다. public이면 해당 Secret은 생략 가능.

전제

• prego-docker: GitHub Actions build-and-push 워크플로가 repository_dispatch 이벤트 custom_app_updated를 수신하도록 되어 있음.
• prego_saas: 커스텀 앱 레포(Pregoi/prego_saas). 여기에 워크플로와 Secret을 추가해야 함.

절차

1. prego-docker에서 워크플로 템플릿 복사

prego-docker 레포의 다음 파일을 복사한다:

• 소스: prego-docker/docs/prego-saas-app-notify-workflow.yml
• 대상: prego_saas/.github/workflows/notify-image-rebuild.yml

(prego_saas 레포를 클론한 뒤, 위 경로에 파일을 생성하거나 내용을 붙여넣는다.)

2. PREGODOCKER_DISPATCH_PAT Secret 설정 (토큰 발급 → Secret 등록)

2.1 토큰 발급 위치

GitHub에서 Personal Access Token(PAT)을 만드는 곳:

1. 브라우저에서 https://github.com 로그인.
2. 우측 상단 프로필 사진 클릭 → Settings.
3. 왼쪽 맨 아래 Developer settings 클릭.
4. Personal access tokens → Tokens (classic) 또는 Fine-grained tokens 중 하나 선택 후 Generate new token.

항목	설명
진입 경로	GitHub.com → 프로필 메뉴 → Settings → Developer settings → Personal access tokens
용도	prego_saas 워크플로가 다른 레포(Pregoi/prego-docker) 로 repository_dispatch API를 호출할 때 인증에 사용.

2.2 Classic PAT로 발급하는 경우

1. Tokens (classic) → Generate new token (classic).
2. Note: 예) prego_saas dispatch prego-docker.
3. Expiration: 원하는 기간(90일, 1년, No expiration 등).
4. Scopes:
   • prego-docker가 private 레포이면: repo 체크 (전체 체크).
   • prego-docker가 public 레포여도: repo 체크해 두면 안전(public repo read로는 repository_dispatch 호출 권한이 부족할 수 있음).
5. Generate token 클릭 후 한 번만 표시되는 토큰 값을 복사해 안전한 곳에 보관.

2.3 Fine-grained PAT로 발급하는 경우

1. Fine-grained tokens → Generate new token.
2. Token name: 예) prego_saas dispatch.
3. Expiration: 원하는 기간.
4. Repository access: Only select repositories → Pregoi/prego-docker 선택.
5. Permissions → Repository permissions:
   • Actions: Read and write (또는 Contents: Read만으로는 repository_dispatch가 안 될 수 있으므로, Actions: Read and write 권장).
6. Generate token 후 토큰 값 복사.

2.4 prego_saas 레포에 Secret 등록

1. https://github.com/Pregoi/prego_saas (본인 조직/레포 경로에 맞게) 이동.
2. Settings → Secrets and variables → Actions.
3. New repository secret 클릭.
4. Name: PREGODOCKER_DISPATCH_PAT (이름 오타 없이 정확히).
5. Secret: 위에서 복사한 PAT 값 붙여넣기.
6. Add secret 저장.

이후 prego_saas의 notify-image-rebuild 워크플로는 GH_TOKEN에 이 값을 넣어 POST .../repos/Pregoi/prego-docker/dispatches를 호출한다.

3. 동작 확인

• prego_saas의 main / staging / develop / version-16에 push하거나, 태그 v*.*.*를 push한다.
• prego_saas의 Actions에서 notify-image-rebuild 워크플로가 성공하는지 확인한다.
• prego-docker의 Actions에서 build-and-push가 repository_dispatch로 실행되고, 이미지가 pregoapp-<short_sha> 등으로 푸시되는지 확인한다.

---

prego-docker에 등록할 Secret (prego_saas가 private일 때)

빌드 중 bench init이 https://github.com/Pregoi/prego_saas 을 clone할 때, 해당 레포가 private이면 인증이 필요하다. prego-docker 레포에 clone 전용 토큰을 Secret으로 등록해야 한다.

1. 토큰 발급 (prego_saas 읽기 권한)

• 위치: GitHub → 본인 프로필 → Settings → Developer settings → Personal access tokens.
• Classic PAT: Scopes에서 repo 체크 (prego_saas가 private이면 필수).
• Fine-grained PAT: Repository access에 Pregoi/prego_saas 선택, Contents: Read-only.
• 이 토큰은 “prego_saas 레포를 clone할 수 있는 권한”만 있으면 되고, prego-docker 레포를 건드릴 권한은 필요 없다.

2. prego-docker 레포에 Secret 등록

1. https://github.com/Pregoi/prego-docker → Settings → Secrets and variables → Actions.
2. New repository secret 클릭.
3. Name: PREGO_SAAS_APP_CLONE_TOKEN
4. Secret: 위에서 만든 PAT 값 붙여넣기.

3. 빌드에서 사용 (구현 완료)

• prego-docker의 build.yml은 secrets: clone_token=${{ secrets.PREGO_SAAS_APP_CLONE_TOKEN }} 로 빌드에 전달한다.
• apps.json에 prego_saas(태그)가 포함되어 있으며, bench init 시에만 clone이 일어난다. Dockerfile은 RUN --mount=type=secret,id=clone_token 으로 토큰을 읽어 clone URL만 치환하고, 별도 APP_SHA 블록은 없다.
• prego_saas가 public이면 이 Secret을 등록하지 않아도 되며, 토큰이 비어 있으면 인증 없이 clone을 시도한다.

---

빌드 실패 시 (exit 128 · exit 167)

• exit 128 (git clone): prego-docker-exit-128-duplicate-clone-resolution-plan — 과거 원인(중복 clone). 현재는 tag 기반 단일 bench init.
• exit 167 (bench init/uv): prego-docker-bench-init-uv-resolver-resolution-plan.

참고

• 기획서: prego-docker-implementation-plan §6 (custom app 자동 재빌드).
• prego-docker README: “Setting up prego_saas”, “Required GitHub Secrets” 섹션.