Release Management

Release Management

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

척척학사 백엔드의 버전, 정식 릴리즈, hotfix와 배포 기록 정책을 정리합니다. 릴리즈 브랜치는 QA 대상을 고정하고, 태그와 GitHub Release는 실제 운영 반영 범위를 식별합니다.

버전 형식

백엔드 버전은 Semantic Versioning의 MAJOR.MINOR.PATCH 형식을 사용합니다.

변경	증가 버전	예시
호환되지 않는 공개 API 또는 운영 방식 변경	MAJOR	1.4.2 → 2.0.0
호환되는 기능 추가	MINOR	1.4.2 → 1.5.0
버그 수정, 리팩터링, 설정·문서 보정	PATCH	1.4.2 → 1.4.3

각 숫자는 0 또는 선행 0 없는 양의 정수여야 합니다. 01.2.3, 1.2, prerelease와 build suffix는 사용하지 않습니다.

릴리즈 브랜치는 release/v{버전}, 운영 배포 태그는 be-v{버전} 형식입니다. 릴리즈 브랜치, 운영 배포 입력값과 태그의 버전은 같아야 합니다.

정식 릴리즈

feat/{issue-number}
  → dev 병합
  → release/v1.2.0 생성
  → Dev Lambda 배포와 QA
  → main 병합
  → main에서 1.2.0으로 Prod Lambda 배포
  → be-v1.2.0 태그와 GitHub Release 확인
  → main을 dev와 진행 중인 release 브랜치에 역병합

QA 중 수정은 대상 릴리즈 브랜치에서 fix/{issue-number}를 만들고 같은 릴리즈 브랜치로 PR을 보냅니다. 수정 뒤 Dev Lambda를 다시 배포해 확인합니다. 배포가 끝난 릴리즈 브랜치는 다음 릴리즈에 재사용하지 않습니다.

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

Hotfix

긴급 수정은 main에서 hotfix/{issue-number}를 만듭니다.

마지막 성공 태그 be-v1.2.0
  → hotfix 검증과 main 반영
  → 다음 PATCH 버전 1.2.1 확인
  → main에서 Prod Lambda 배포
  → be-v1.2.1 태그와 GitHub Release 확인
  → main을 dev와 진행 중인 release 브랜치에 역병합

마지막 성공 be-v* 태그를 기준으로 다음 PATCH 버전을 제안합니다. 이미 존재하는 버전이나 MAJOR·MINOR 변경이 필요하면 임의로 결정하지 않고 팀과 확인합니다.

배포 성공 판단

다음 항목이 모두 확인돼야 운영 배포가 완료된 것입니다.

1. prod Flyway migration과 테스트가 성공합니다.
2. 새 Lambda Version이 Active 상태가 됩니다.
3. Lambda Alias가 새 Version을 가리킵니다.
4. Actions Summary와 prod-lambda-deployment-metadata artifact가 생성됩니다.
5. 배포 커밋에 be-v{버전} annotated tag가 생성됩니다.
6. 같은 태그의 GitHub Release가 생성됩니다.

Alias 검증 전에 실패하면 배포 실패입니다. Alias 검증 뒤 태그 또는 GitHub Release 게시에 실패하면 새 Lambda가 실행 중일 수 있으므로 배포 상태와 릴리즈 기록을 따로 확인합니다.

PR 라벨과 릴리즈 노트

GitHub Release의 자동 생성 릴리즈 노트는 병합 PR의 대표 라벨로 분류합니다.

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

PR에는 변경의 주된 성격에 맞는 대표 라벨을 붙입니다. 릴리즈 노트에서 제외할 PR은 skip-release-notes를 사용합니다. 여러 라벨이 있으면 .github/release.yml에 선언된 순서로 한 구역에 분류됩니다.

태그와 GitHub Release

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

보호 규칙

• 운영 배포는 main에서만 실행합니다.
• Workflow 실패를 성공 배포로 기록하지 않습니다.
• 롤백해도 기존 태그를 삭제하거나 다른 커밋으로 옮기지 않습니다.
• 롤백 뒤 다시 배포하면 원인과 버전 증가 방식을 확인하고 새 버전을 사용합니다.
• main의 수정은 dev와 진행 중인 릴리즈 브랜치에 반영합니다.

릴리즈 기록 게시 실패 복구

태그 push는 성공했지만 GitHub Release 생성만 실패했다면 아래 값이 모두 일치할 때 같은 태그에 Release만 복구합니다. prod Workflow를 다시 실행하거나 태그를 다시 만들지 않습니다.

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"

문서 갱신

.github/workflows/deploy-prod-lambda.yml 또는 .github/release.yml의 입력값, 검증 단계, 태그 생성과 릴리즈 노트 분류가 바뀌면 이 페이지를 함께 고칩니다. 배포 실행과 롤백 절차가 바뀌면 Deployment and Operations도 갱신합니다.