배포

원문 보기 위키 갱신 2026.10.07

배포 (Publishing)

npm 패키지는 .github/workflows/deploy_packages.yml 워크플로우의 CI/CD를 통해 배포돼요. master에 병합되는 모든 커밋은 모든 공개 패키지의 새 버전을 검사하며, 새 버전은 자동으로 npm에 배포돼요.

출처: 문서

본문

npm

새 릴리스 만들기

릴리스는 changesets로 처리되며 "Version Packages" PR이 병합될 때마다 트리거돼요. 보통 매주 화요일 정오 CET 무렵에 이루어져요.

Next 라인 릴리스 과정

PR 검사: 팀에 알리고 이 버전에 대해 병합 대기 중인 미해결 PR이 없는지 확인하세요. 매끄러운 릴리스일을 보장하기 위해 제때 이루어져야 해요. 있으면 메인테이너와 영향받는 코드의 관련 소유자에게 릴리스 마감을 상기시켜 연락하세요.
main 브랜치 잠그기
다른 메인테이너가 새로 병합하지 못하게 main 브랜치를 잠그세요. 릴리스가 성공적으로 배포될 때까지 main 브랜치를 잠그지 마세요.
코어 메인테이너는 admin 오버라이드를 사용해 마지막 PR(Version Packages PR 포함)을 여전히 병합할 수 있어요.
참고: 브랜치를 잠그려면 admin 권한이 필요해요. 필요한 권한이 부족하면 코어 메인테이너에게 이를 대신해 수행하도록 연락하세요.
Version Packages (next) Pull Request 확인
version packages PR 제목을 보고 배포하는 버전이 올바른지 검증하세요. 제목은 "Version Packages (next)"여야 해요.
.changeset 폴더의 pre.json을 확인하세요 — 상단 근처에 "mode": "pre"가 있어야 해요. "mode": "exit"를 만나거나 파일이 없다면 mainline 릴리스임을 나타내요.
실행 중인 활성/미완료 sync_version-packages 액션(https://github.com/backstage/backstage/actions/workflows/sync_version-packages.yml)이 없는지 확인하세요.
main 브랜치를 잠그면 새 것이 생성되지 못하게 하지만, 잠금 해제 후 실행 중인 액션을 다시 확인하세요. 대기 중인 자동 병합 PR이 병합될 수 있기 때문이에요.
Version Packages (next) Pull Request가 병합될 충분한 승인을 받았는지 확인하세요.
docs/releases 아래 pull request의 변경 파일에서 생성된 changelog를 확인해 예상치 못한 major 증가가 없는지 확인하세요. 예를 들어 파일을 검색해서요.
변경 사항 검토 및 승인
코어 메인테이너에게 pull request 병합을 요청하세요.
참고: prettier 작업이 통과하고 다른 모든 것이 초록색으로 보이는 한 microsite 빌드 단계는 건너뛸 수 있어요.

Version Packages (next) Pull Request를 병합하면 배포 워크플로우가 트리거돼요. 배포 워크플로우를 따라가세요. 불안정함을 발견하면(예: 빌드가 불안정하거나 릴리스 단계가 npm에 배포할 때 오류가 나는 경우) 워크플로우를 다시 시작하세요.

릴리스가 배포될 준비가 되면, 메인테이너는 Backstage Discord 서버의 비공개 #maintainers 채널에서 알림을 받아요. 그런 다음 알림 메시지에 연결된 publishing workflows 페이지에서 배포 워크플로우를 시작해요. publishing workflows 페이지에는 "Run workflow"라는 드롭다운 메뉴가 있으며, 이는 릴리스 담당자가 Discord 알림에서 받은 SHA를 붙여넣고 워크플로우를 실행하려 클릭하는 폼을 열어요.

릴리스 축하해요! 이제 Discord의 #announcements 채널에 릴리스 태그로 연결되는 게시물이 있어야 해요 — 링크와 태그가 예상대로 보이는지 확인하세요. Discord에 알림이 나간 후 main 브랜치를 잠금 해제하면 릴리스가 완료돼요.

Main 라인 릴리스 과정

main 라인 릴리스에 대한 추가 단계

릴리스 모드를 exit 프리릴리스 모드로 전환하세요. 이것은 마지막 Next 라인 릴리스 후 언제든지 할 수 있어요.
.changeset/pre.json에서 mode가 exit로 설정되어 있는지 확인하세요. mode: "pre"를 만나면 next 라인 릴리스를 나타내요.
Version Packages Pull Request 확인
"major" 및 "breaking" 언급을 확인하고 현재 릴리스에서 예상되는지 확인하세요.
배포하는 버전이 올바른지 검증하세요.
릴리스 노트 만들기
릴리스 노트를 만들기 위한 릴리스 노트 템플릿(.release-notes-template.md)이 있어요. 마지막 main 라인 릴리스 후에 만들어 두어 그 달의 주요 변경 사항을 추적할 수 있어요.
콘텐츠는 릴리스 달의 커뮤니티 작업을 보여 주는 관련성에 의해 선택돼요.
새로 추가된 패키지나 기능을 언급하세요.
보안 수정을 언급하세요.
릴리스 노트 PR 만들기
릴리스 노트 파일을 /docs/releases/vx.y.0.md로 추가하세요.
마지막으로 메타데이터 헤더 없이 콘텐츠를 Version Packages Pull Request의 설명에 복사하세요.
릴리스가 배포된 후 GitHub 저장소에서 새로 만든 릴리스를 편집하고 텍스트 콘텐츠를 릴리스 노트로 교체하세요.

릴리스 모드 전환

프리릴리스 모드 진입: yarn changeset pre enter next & PR 만들기 + 변경 병합
프리릴리스 모드 종료: yarn changeset pre exit & PR 만들기 + 변경 병합
mainline 릴리스 전에 해야 해요.
시간에 민감하지 않아요. 다음에 일어나는 릴리스에 영향을 미쳐요.

긴급 릴리스 과정

이 긴급 릴리스 과정은 Backstage 메인테이너만을 위한 것이에요.

patch 릴리스를 만들고 싶은 master로 가는 PR이 하나 이상 있다면, 각 PR에 대해 다음 명령을 실행해 patch 릴리스 대기열에 추가하세요.

yarn patch-pr <pr-number> <description>

이것은 수정의 설명을 담은 .patches/ 디렉터리(예: .patches/pr-12345.txt)에 patch 파일을 만듭니다. sync_patch-release.yml 워크플로우가 이 patch 파일을 자동으로 감지해 "Patch Release" PR을 만들거나 갱신합니다.

워크플로우는 다음을 수행합니다.

patch release PR이 없으면 자동으로 생성
patch 파일이 추가, 수정, 제거되면 기존 PR 갱신
모든 patch 파일이 제거되면 PR 브랜치를 닫고 삭제

"Patch Release" PR이 승인되고 병합되면 patch 릴리스가 자동으로 만들어집니다. patch 파일은 patch 릴리스가 병합된 후 master 브랜치에서 자동으로 제거됩니다. 여기서부터 patch 릴리스 과정은 Discord의 #maintainers 채널 알림으로 시작하는 일반 릴리스 과정과 같습니다.

위 과정이 실패하면 아래 문서화된 수동 과정으로 대체하거나, ./scripts/patch-release-for-pr.js <pr-number> <pr-number-2> ... 스크립트를 실행해 patch release PR을 수동으로 만들 수 있습니다.

이전 과정

이것은 patch 스크립트 이전에 사용했던 이전의 수동 과정이며 참조용으로 제공합니다.

이 예시에서는 @backstage/plugin-foo 패키지를 예시로 사용하고 master 브랜치에서 현재 버전 6.5.0이라고 가정합니다.

v1.18.0 Backstage 릴리스에서 출시된 @backstage/plugin-foo의 6.5.0 버전에 심각한 버그가 도입된 경우, 다음 과정을 사용해 patch 릴리스 v1.18.1에서 긴급 수정을 버전 6.5.1으로 릴리스합니다.

patch해야 하는 릴리스 또는 릴리스들을 식별하세요. 필요하면 항상 가장 최근 major 또는 minor main-line 릴리스를 patch해야 하며, 이 예시에서는 v1.18.0이 될 거예요. 수정은 오래된 major 버전으로 백포트해야 할 수도 있으며, 그 경우 패키지를 각 새 major 버전으로 올린 것 바로 이전의 main-line 릴리스를 patch하려 할 거예요.
patch해야 하는 각 릴리스에 대해 다음 단계를 반복하세요.
patch 중인 릴리스에 대한 patch 브랜치가 있는지 확인하세요. patch가 이미 존재하면 기존 브랜치를 재사용하세요. 브랜치는 항상 정확히 patch/<release>로 이름을 지정해야 해요.

git checkout v1.18.0git checkout -b patch/v1.18.0git push --set-upstream origin patch/v1.18.0

patch/v1.18.0 브랜치를 기준으로 수정을 위한 새 브랜치를 만드세요. 이 브랜치는 뭐든 이름을 지을 수 있지만, 다음 명명 패턴이 적합할 수 있어요.

git checkout -b ${USER}/plugin-foo-v1.18.0-fix

수정을 적용하는 단일 커밋을 만들고, 다른 것은 없게 하세요.
영향받는 패키지에 대한 changeset을 만든 다음 저장소 루트에서 yarn release를 실행해 changeset을 패키지 버전 증가와 changelog 항목으로 변환하세요. 이 변경 사항을 두 번째 "Generated release" 커밋으로 커밋하세요.
두 커밋을 담은 기본 브랜치(patch/v1.18.0)로 가는 PR을 만드세요.
PR 본문을 추가하세요. 릴리스 설명으로 사용됩니다. 보통 "This release fixes ..." 같은 것입니다.
PR을 patch/v1.18.0으로 검토/병합하세요. 이는 자동으로 릴리스를 트리거해요.
patch PR에서 패키지의 새 버전과 새 릴리스 버전을 조회하세요. 이것들은 패키지 package.json과 루트 package.json에서 찾을 수 있으며, 이 경우 6.5.1과 v1.18.1이 될 거예요. 이 버전들은 나중에 필요할 거예요.
PR 병합 후 patch 브랜치의 최신 버전을 가져왔는지 확인하세요: git fetch.
각 릴리스에 대한 수정이 만들어지면 수정을 master 브랜치에도 적용해야 해요. 다음을 포함하는 PR을 만드세요.
수정. patch 브랜치에서 cherry-pick할 가능성이 높아요: git cherry-pick origin/patch/v1.18.0^
patch 브랜치 끝에서 모든 patch된 패키지의 갱신된 CHANGELOG.md, git checkout origin/patch/v1.18.0 -- {packages,plugins}/*/CHANGELOG.md. patch가 어떤 next-line 릴리스 다음에 일어난다면 changelog에서 그 항목들을 복원해야 하며, patch 릴리스 항목을 모든 next-line 릴리스 항목 아래에 배치해야 한다는 점을 주의하세요.
"Applied the fix from version 6.5.1 of this package, which is part of the v1.18.1 release of Backstage." 메시지가 있는 changeset.

문제 해결

어떤 이유로 릴리스 워크플로우가 트리거되지 않는 경우 (예: GitHub 사고)

메인테이너 중 한 명에게 master 브랜치에서 "Unconditionally trigger the release job to run" 확인란을 설정한 Deploy packages 워크플로우를 트리거하도록 요청하세요. 먼저 원래 실패한 릴리스 시도 이후 master에 상당한 것이 push되지 않았는지 검증하세요! 이런 이유로 각 릴리스가 통과될 때까지 master 브랜치를 잠가 두는 것이 현명해요.

릴리스가 패키지를 성공적으로 배포했지만 릴리스 마무리에 실패한 경우

일시적인 실패라면 릴리스 워크플로우를 다시 트리거해도 안전해요.

다시 트리거해도 도움이 되지 않거나 않을 경우, 릴리스를 완료하기 위해 다음 단계를 취할 수 있어요.

릴리스에 대한 git 태그가 아직 없으면 수동으로 만드세요.
새 GitHub 릴리스를 수동으로 만드세요.
다음 요청을 사용해 저장소 dispatch 워크플로우를 트리거하세요. <VERSION>을 v 접두사 없이 릴리스 버전으로 교체하세요.

curl -L \  -X POST \  -H "Accept: application/vnd.github+json" \  -H "Authorization: Bearer *** auth token)" \  -H "X-GitHub-Api-Version: 2022-11-28" \  https://api.github.com/repos/backstage/backstage/dispatches \  -d '{"event_type":"release-published","client_payload":{"version":"<VERSION>"}}'

Discord의 #announcements 채널에 수동으로 메시지를 게시하세요.

배포