릴리스 안내

버전과 파일명 계약

항목	1.8.7 예시
저장소 `VERSION`	`1.8.7`
Git tag	`v1.8.7`
Docker image	`jupiq:v1.8.7`
Release asset	`jupiq-v1.8.7.tar.gz`
로그인 화면	`1.8.7` + commit 요약
프로필 메뉴	`1.8.7`
Version API	version + commit + build time

Semantic Versioning을 따릅니다. 호환되지 않는 변경은 major, 호환 기능은 minor, 호환 수정은 patch를 올립니다. latest 태그는 오프라인 배포 기준으로 사용하지 않습니다.

태그 릴리스 파이프라인

CI 통과
Go vet/test, PostgreSQL 통합 테스트, React type/test/build, 멀티스테이지 Docker build가 성공해야 합니다.
VERSION 변경과 태그
문서와 VERSION을 같은 버전으로 갱신하고 vX.Y.Z annotated tag를 생성합니다.
태그·버전 검증
Workflow가 GITHUB_REF_NAME == v$(cat VERSION)인지 확인하고 README·Compose·OpenAPI·Pages의 버전 계약을 검사합니다.
멀티스테이지 이미지 빌드
React web/dist, Go 실행파일과 version/commit/build time을 최종 이미지에 넣습니다.
단일 archive 생성
docker save jupiq:vX.Y.Z | gzip으로 정확한 파일명을 만듭니다.
삭제 후 복원 검증
runner의 원본 이미지를 지우고 tar.gz에서 다시 load해 태그와 OCI label을 확인합니다.
망 차단 Smoke Test
--internal Docker network에서 health/readiness, 버전, SPA, OpenAPI, Bootstrap 로그인, 대시보드와 MCP initialize를 확인합니다.
SHA-256 공개
최종 tar.gz의 SHA-256을 계산해 Release 본문과 workflow summary에 기록합니다.
GitHub Release
tar.gz 하나만 업로드하고 검증 명령과 자동 릴리스 노트를 제공합니다.

로컬 빌드와 검증

make lint
make test
make image       # jupiq:v1.8.7
make package     # dist/jupiq-v1.8.7.tar.gz
make verify

릴리스 Workflow는 추가로 postgres:16-alpine을 미리 준비하고 외부 통신이 막힌 내부 Docker network에서 scripts/offline-smoke-test.sh를 실행합니다. PostgreSQL 이미지는 release asset에 포함되지 않습니다.

단일 자산 검사: dist/에 jupiq-v${GITHUB_REF_NAME#v}.tar.gz가 아니라 jupiq-${GITHUB_REF_NAME}.tar.gz, 즉 jupiq-v1.8.7.tar.gz 하나만 있는지 Workflow가 검사합니다.

오프라인망에서 사용

JUPIQ_ARCHIVE_SHA256='릴리스-본문의-SHA256'
printf '%s  %s\n' "${JUPIQ_ARCHIVE_SHA256}" jupiq-v1.8.7.tar.gz | sha256sum -c -
gzip -t jupiq-v1.8.7.tar.gz
gzip -dc jupiq-v1.8.7.tar.gz | docker load
docker image inspect jupiq:v1.8.7
# 설치 가이드의 네 줄로 .env를 직접 만든 뒤 실행
docker run -d --name jupiq --restart unless-stopped --init \
  --env-file .env -p 127.0.0.1:8080:8080 \
  --read-only --tmpfs /tmp:size=64m,mode=1777 \
  --cap-drop ALL --security-opt no-new-privileges:true \
  jupiq:v1.8.7

GitHub Release 자산에는 서비스 이미지 tar.gz 하나만 있고 .env, .env.example, compose.example.yaml은 포함되지 않습니다. Compose를 사용하려면 같은 v1.8.7 태그 소스의 .env.example과 compose.example.yaml을 별도로 반입하고 docker compose --env-file .env -f compose.example.yaml up -d를 실행하세요.

이미지를 private offline registry에 다시 push할 수 있지만 원본 태그를 보존하고 조직 승인 metadata와 연결하세요. 네 환경변수 작성과 보안 옵션은 설치 가이드를 참고합니다.

롤백 원칙

현재와 직전 승인 이미지를 동시에 보존
업그레이드 전 PostgreSQL 복구 지점 생성
릴리스 노트에서 migration 역호환 여부 확인
오류 시 먼저 새 컨테이너 로그와 correlation ID 보존
DB 호환 시 이전 image tag로 복귀
비호환 migration이면 이전 DB 복원 후 이전 image 기동

이미지만 내린 뒤 새 schema의 DB를 그대로 쓰는 것은 안전한 롤백이 아닐 수 있습니다. 반드시 릴리스별 migration 안내와 복구 시험을 기준으로 판단하세요.

공개 릴리스 목록은 GitHub Releases에서 확인할 수 있습니다.

태그, 이미지, 파일 이름을 하나의 버전으로 묶습니다

버전과 파일명 계약

태그 릴리스 파이프라인

로컬 빌드와 검증

오프라인망에서 사용

롤백 원칙