Release Management

Release Management

전환 안내. 이 페이지의 엄격한 prod 버전 검증과 자동 태그·GitHub Release 생성은 backend issue #306의 workflow가 main에 반영된 뒤 적용됩니다. 그전에는 main의 실제 workflow를 기준으로 판단합니다.

왜 버전을 관리하나요

dev에 QA 배포를 계속하면 QA 중인 변경과 새 작업이 같은 브랜치에 섞입니다. 어느 변경을 검증했고 무엇을 운영에 보낼지 빠르게 알기 어렵습니다.

릴리즈 브랜치와 버전을 함께 사용하면 QA 대상 commit을 고정할 수 있습니다. 배포 뒤에는 태그와 GitHub Release로 운영 반영 범위를 다시 확인할 수 있습니다.

한눈에 보는 흐름

flowchart LR
    Feature["feat/{issue-number}"] --> Dev["dev"]
    Dev --> Release["release/v{버전}"]
    Release --> QA["Dev Lambda QA"]
    QA --> Main["main"]
    Main --> Prod["Prod Lambda 배포"]
    Prod --> Tag["be-v{버전} tag + GitHub Release"]
    Main --> Dev

Loading

단계	담당 작업	결과
개발	feat/{issue-number}를 dev로 병합	다음 릴리즈 후보 누적
QA	release/v{버전}에서 Dev Lambda 배포·검증	QA 범위 고정
운영	release 브랜치를 main으로 병합하고 prod 배포	be-v{버전}과 GitHub Release 생성
동기화	main을 dev와 진행 중 release 브랜치에 역병합	QA 수정 누락 방지

버전 형식

버전은 최종 MAJOR.MINOR.PATCH 형식만 사용합니다. 각 숫자는 0 또는 선행 0 없는 양의 정수여야 합니다.

• MAJOR는 호환되지 않는 공개 API 또는 운영 방식 변경입니다.
• MINOR는 호환되는 기능 추가입니다.
• PATCH는 버그 수정, 리팩터링, 설정·문서 보정 등 기존 동작을 깨지 않는 배포입니다.

01.2.3, 1.2, 1.2.3-rc.1, 1.2.3+build.1은 사용하지 않습니다. release/v{버전}과 운영 배포 입력값은 항상 같아야 합니다.

정식 릴리즈

1. dev에서 release/v{버전}을 만듭니다.
2. release 브랜치를 Deploy to Dev Lambda로 배포해 QA합니다.
3. QA 수정은 대상 release 브랜치에서 fix/{issue-number}을 만들어 병합하고 다시 배포해 확인합니다.
4. QA가 끝나면 release 브랜치를 main에 병합합니다.
5. Deploy to Prod Lambda를 main에서 실행하고 확정한 버전을 입력합니다.
6. Alias 검증과 metadata artifact 생성이 끝나면 같은 commit에 be-v{버전} annotated tag와 GitHub Release가 생성됐는지 확인합니다.
7. main을 dev와 진행 중인 모든 release/* 브랜치에 역병합합니다.

실제 Actions 실행, Lambda 산출물, 환경 설정, 롤백은 Deployment and Operations를 따릅니다.

Hotfix

1. main에서 hotfix/{issue-number}을 만듭니다.
2. 수정과 검증을 마친 뒤 main에 병합합니다.
3. 마지막 성공 be-v*의 PATCH를 1 증가한 버전을 확인하고 승인합니다. 예를 들어 be-v1.2.3 다음은 1.2.4입니다.
4. main에서 prod 배포를 실행합니다.
5. 완료 뒤 main을 dev와 진행 중인 모든 release/* 브랜치에 역병합합니다.

PR 라벨과 Release Notes

GitHub Release Notes는 병합 PR의 라벨로 분류합니다.

라벨	Release Notes 구역
✨ Feature, 📬 API	새 기능
🐞 BugFix	버그 수정
🔨 Refactor	개선
📃 Docs	문서
🌏 Deploy, ⚙ Setting	운영 및 배포
skip-release-notes	릴리즈 노트에서 제외

PR에는 변경의 주된 성격에 맞는 라벨을 붙입니다. 여러 라벨이 있으면 Release Notes 설정에 선언된 순서로 분류됩니다.

태그와 GitHub Release

• 운영 배포 성공 후에만 be-v{버전} annotated tag를 만듭니다.
• 이미 게시한 태그는 삭제하거나 다른 commit으로 이동하지 않습니다.
• GitHub Release는 태그, 제품 버전, commit SHA, Lambda published version, alias version과 자동 생성 릴리즈 노트를 함께 기록합니다.
• be-v* 태그와 GitHub Release는 별도 객체이므로 둘 다 존재하는지 확인합니다.

릴리즈 기록 게시 실패 복구

Alias 검증 전 실패는 배포 실패입니다. Alias 검증 뒤 태그 또는 GitHub Release 게시가 실패하면 Lambda 배포는 성공했지만 릴리즈 기록 게시가 실패한 부분 성공입니다.

태그 push는 성공했지만 GitHub Release 생성만 실패했다면 아래 값이 모두 일치할 때 같은 태그에 Release만 복구합니다.

1. 실패한 Actions run의 headSha.
2. annotated tag를 역참조한 commit SHA.
3. metadata artifact의 commit_sha, published_version, alias_version.
4. 현재 Lambda Alias가 가리키는 Version.

값이 다르거나 Release가 이미 있으면 중단하고 후속 배포나 수동 변경 여부를 먼저 조사합니다. 부분 성공을 복구하려고 prod Workflow를 다시 실행하거나 태그를 다시 만들지 않습니다.

GitHub Release만 복구하는 명령 예시

RUN_ID="<실패한 Actions run ID>"
artifact_dir="$(mktemp -d)"

gh run download "$RUN_ID" \
  --name prod-lambda-deployment-metadata \
  --dir "$artifact_dir"

metadata_file="$artifact_dir/prod-lambda-deployment.txt"
metadata_value() {
  awk -F= -v key="$1" '$1 == key { sub(/^[^=]*=/, ""); print; exit }' "$metadata_file"
}

release_version="$(metadata_value release_version)"
release_tag="$(metadata_value release_tag)"
commit_sha="$(metadata_value commit_sha)"
function_name="$(metadata_value function_name)"
alias_name="$(metadata_value alias)"
published_version="$(metadata_value published_version)"
alias_version="$(metadata_value alias_version)"
run_sha="$(gh run view "$RUN_ID" --json headSha --jq '.headSha')"

git fetch origin "refs/tags/$release_tag:refs/tags/$release_tag"
tag_sha="$(git rev-parse "$release_tag^{commit}")"
live_alias_version="$(aws lambda get-alias \
  --function-name "$function_name" \
  --name "$alias_name" \
  --query 'FunctionVersion' \
  --output text)"

test "$run_sha" = "$commit_sha"
test "$tag_sha" = "$commit_sha"
test "$published_version" = "$alias_version"
test "$live_alias_version" = "$alias_version"

release_notes=$(printf -- '- Product version: `%s`\n- Commit SHA: `%s`\n- Lambda published version: `%s`\n- Lambda alias version: `%s`\n' \
  "$release_version" \
  "$commit_sha" \
  "$published_version" \
  "$alias_version")

gh release create "$release_tag" \
  --verify-tag \
  --target "$commit_sha" \
  --title "$release_tag" \
  --generate-notes \
  --notes "$release_notes"