Enterprise Live Migrations를 사용하여 리포지토리 마이그레이션

GitHub Enterprise Server에서 GHE.com으로 전환하면서 가동 중지 시간을 최소화합니다.

누가 이 기능을 사용할 수 있나요?

Site administrators on GitHub Enterprise Server who are also enterprise owners on GHE.com.

이 기사에서

팁

이 가이드를 따르면 기업용 라이브 마이그레이션 CLI 참고 문서 을 참조하여 자세한 사용 정보를 확인할 수 있습니다. 오류가 발생하면 GitHub Enterprise Server에서 GHE.com 실시간 마이그레이션 문제 해결을 참조하세요.

사전 요구 사항

환경 및 개발자가 마이그레이션할 준비가 되었는지 확인합니다. GitHub Enterprise Server에서 GHE.com 실시간 마이그레이션 준비을(를) 참조하세요.

1. 구성하기 GitHub Enterprise Server

토큰을 만들고 마이그레이션을 수행하기 전에 인스턴스에 GitHub Enterprise Server 일부 구성을 설정해야 합니다. 이러한 구성 값은 모든 ELM 마이그레이션에 적용됩니다. 개발자는 GitHub Enterprise Server 새 구성을 적용할 때 짧은 가동 중지 시간이 발생할 수 있습니다.

  1. SSH를 GitHub Enterprise Server 통해 관리 셸에 액세스합니다. 관리 셸(SSH)에 액세스을(를) 참조하세요.

  2. 를 사용하여 다음 구성 변수를 ghe-config설정합니다.

    예를 들어: ghe-config app.elm-exporter.enabled true

    변수이 값으로 설정합니다.
    app.elm-exporter.enabledtrue
    app.elm.internal-webhooks-enabledtrue
    app.elm-exporter.webhooks-loopback-address-enabledtrue
    secrets.elm-exporter.migration-target-url대상 엔터프라이즈의 API URL입니다(예: https://api.octocorp.ghe.com). URL의 끝에 후행 슬래시를 포함하지 마세요 .
    secrets.elm-exporter.source-user연산자의 토큰과 연결된 사용자 이름입니다 GitHub Enterprise Server . 이는 사용자 이름이 GitHub Enterprise Server어야 합니다. 다른 사람이 이 토큰을 만들려는 경우 여기에 있는 값을 해당 사용자 이름으로 설정해야 합니다.

ghe-admin 사용자를 권장합니다. |

  1. 구성을 적용하세요.

    Shell
    ghe-config-apply

  2. SSH 세션을 종료합니다. 로컬 터미널 세션에서 나머지 명령을 실행합니다.

2. 엔터프라이즈 액세스를 사용하여 운영자 토큰 만들기

운영자는 personal access token (classic)을 사용하여 원본 엔터프라이즈와 대상 엔터프라이즈 모두에 인증해야 합니다. 토큰을 만드는 방법에 대한 지침은 개인용 액세스 토큰 관리을 참조하세요.

다음 단계에서 필요하므로 두 토큰을 모두 기록해 둡니다.

  1. ** GitHub Enterprise Server **에서 personal access token (classic)를 만들고 필요한 범위를 선택합니다.

    • admin:enterprise

    를 구성할 ELM CLI때 이 토큰을 원본 토큰으로 사용합니다.

  2. ** GHE.com **에서 personal access token (classic)를 만들고 필요한 범위를 선택합니다.

    • admin:enterprise
    • admin:org

    를 구성할 ELM CLI때 이 토큰을 대상 토큰으로 사용합니다.

3. 명령줄 도구 구성 ELM

의 확장을 사용하여 로컬 터미널 세션에서 마이그레이션을 실행합니다 GitHub CLI.

  1. GitHub CLI 로컬 컴퓨터에 설치합니다. 버전 2.0 이상을 사용해야 합니다.

  2. ELM 확장을 설치합니다.

    Shell
    gh extension install github/gh-elm

  3. 설치 마법사를 시작하여 확장을 구성합니다.

    Shell
    gh elm configure

  4. 설치 마법사의 지침에 따라 원본 및 대상 및 이전 단계에서 만든 토큰에 대한 API URL(예: https://api.SUBDOMAIN.ghe.com)을 제공합니다.

이러한 값은 모든 gh elm 명령에서 CLI 플래그로 제공될 수도 있습니다. 이 플래그는 구성보다 우선합니다. 예: --target-url https://api.SUBDOMAIN.ghe.com.

이 설치 프로세스는 운영 체제의 구성 디렉터리에 있는 플랫폼별 구성 파일에 URL을 저장합니다 gh-elm/config.json. 액세스 토큰은 컴퓨터의 비밀 스토리지에 안전하게 저장됩니다.

4. 실시간 마이그레이션 비밀 구성

엔터프라이즈 액세스 권한이 있는 운영자 토큰 외에도 원본 및 대상 조직에 대한 토큰 personal access token (classic) 을 만들어야 합니다. 마이그레이션하는 모든 조직에 대해 이러한 단계를 반복해야 합니다.

액세스 토큰 만들기

ELM는 마이그레이션의 원본과 대상 모두에 대해 personal access token (classic)를 사용하여 인증해야 합니다. 토큰을 만드는 방법에 대한 지침은 개인용 액세스 토큰 관리을 참조하세요.

다음 단계에서 필요하므로 이러한 토큰을 기록해 둡니다.

  1. ** personal access token (classic) **에서 다음 범위로 GitHub Enterprise Server을(를) 만듭니다.

    • repo
    • admin:org
    • admin:repo_hook
    • admin:org_hook

    원본 토큰입니다.

  2. ** personal access token (classic) **에서 다음 범위로 GHE.com을(를) 만듭니다.

    • repo
    • workflow
    • admin:org
    • admin:repo_hook
    • admin:enterprise

    대상 토큰입니다.

    중요

    대상 조직에서 GHE.comSingle Sign-On이 적용되는 경우 SSO에 대한 토큰에 GHE.com 권한을 부여해야 합니다.

조직의 ELM 시크릿 구성

gh elm config 명령을 사용하여 원본 및 대상 액세스 토큰을 설정합니다.

  1. 원본 토큰을 설정합니다.

    Shell
    gh elm config set-source-pat EXISTING-GHES-ORG

    메시지가 표시되면 원본 토큰을 터미널에 붙여넣습니다.

  2. 대상 토큰을 설정합니다.

    Shell
    gh elm config set-target-pat EXISTING-GHES-ORG

    메시지가 표시되면 대상 토큰을 터미널에 붙여넣습니다.

gh elm config org-tokens EXISTING-GHES-ORG을 사용하여 대화형으로 토큰을 설정하거나 https://GHES_HOSTNAME/organizations/EXISTING-GHES-ORG/settings/secrets/elm-exporter/의 조직 설정에서 토큰을 설정할 수도 있습니다.

5. 마이그레이션 만들기

원본 및 대상 리포지토리 세부 정보를 지정하여 새 마이그레이션을 만듭니다.

참고

새 target-org 항목 또는 기존 항목일 수 있습니다. 대상 조직이 아직 없는 경우 마이그레이션 중에 만들어집니다. 그러나 원본 조직의 설정은 마이그레이션되지 않습니다.

Shell
gh elm migration create \
  --source-org EXISTING-GHES-ORG \
  --source-repo EXISTING-GHES-REPO \
  --target-org GHEC-ORG \
  --target-repo NEW-GHEC-REPO

다음은 그 예입니다.

gh elm migration create \
  --source-org my-ghes-org \
  --source-repo my-ghes-repo \
  --target-org my-dr-org \
  --target-repo my-dr-repo

선택적 플래그:

  • --start: 마이그레이션을 즉시 시작할 준비가 되었는지 확인합니다.
  • --target-visibility: 마이그레이션된 리포지토리는 기본적으로 내부 표시 유형으로 만들어지지만 지정할 private수 있습니다.

마이그레이션 ID 저장

다음과 같은 응답이 표시됩니다.

{
  "migrationId": "2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9",
  "expiresAt": "2026-02-11T21:49:33.619162159Z"
}

migrationId 다음 명령에 필요하므로 변수로 내보냅니다. 다음은 그 예입니다.

export MIGRATION_ID='2b5c9eae-b5da-4306-ab04-2a29cc2b7cb9'

6. 마이그레이션 시작

마이그레이션을 아직 시작하지 않은 경우 방금 저장한 마이그레이션 ID를 사용하여 지금 시작합니다.

Shell
gh elm migration start --migration-id $MIGRATION_ID

그러면 백필 및 라이브 업데이트 프로세스가 시작됩니다. ELM 는 이제 원본 리포지토리에서 데이터를 수집하고 지원되는 웹후크 이벤트를 수신 대기합니다.

7. 마이그레이션 모니터링

마이그레이션이 시작되면 새 리포지토리가 표시됩니다 GHE.com. 마이그레이션하는 동안 개발자가 원본 리포지토리에서 계속 작업할 때 초기 데이터 로드로 리포지토리가 채워지고 업데이트가 수신됩니다.

다음 명령을 사용하여 대화형으로 마이그레이션 진행률을 모니터링할 수 있습니다.watch

gh elm migration watch $MIGRATION_ID

이렇게 하면 마이그레이션 상태 API를 폴링하고 현재 진행률을 반영하는 자동 새로 고침 텍스트 UI가 표시됩니다.

migration status를 사용한 프로그래밍 방식의 모니터링

자동화에 적합한 마이그레이션 상태를 원하는 경우 다음 status 명령을 사용합니다.

Shell
gh elm migration status --migration-id $MIGRATION_ID

응답에서 가장 중요한 지표는 combinedState 개체의 상태입니다. 상태가 COMBINED_STATUS_READY_FOR_CUTOVER에 도달하면 다음 단계로 진행할 준비를 해야 합니다. 그러나 개별 리소스가 displayMessage에서 마이그레이션에 실패하면 조사가 필요할 수 있다는 경고가 표시됩니다.

다음은 그 예입니다.

  "combinedState":  {
    "status":  "COMBINED_STATUS_READY_FOR_CUTOVER",
    "displayMessage":  "Ready for cutover (1 resources failed)",
    "repositories":  [
      {
        "repositoryNwo":  "new-test-org/my-new-repo",
        "phase":  "REPOSITORY_PHASE_READY_FOR_CUTOVER",
        "displayStatus":  "Ready for cutover (1 failed)"
      }
    ],
    "readyForCutover":  true,
    "cutoverBlockers":  []
  },

팁:

  • 여러 마이그레이션을 실행하는 경우 .를 사용하여 모든 gh elm migration list마이그레이션의 상태를 확인할 수 있습니다. 이 명령은 기본적으로 진행 중인 마이그레이션을 표시하지만 다음을 통해 --status필터링할 수도 있습니다.
  • 주의가 필요한 실패 상태가 발생하는 경우 GitHub Enterprise Server에서 GHE.com 실시간 마이그레이션 문제 해결을 참조하세요.

8. 마이그레이션 완료

마이그레이션을 중단할 준비가 되면 마이그레이션을 완료할 수 있습니다. 컷오버 프로세스는 원본 리포지토리를 보관 처리하므로, 리포지토리 관리자가 보관 해제하지 않는 한 영구적으로 읽기 전용 상태가 됩니다.

Shell
gh elm migration cutover --migration-id $MIGRATION_ID

마이그레이션을 계속 모니터링합니다. 응답 맨 위에 상태가 표시 MIGRATION_STATUS_COMPLETED 되면 마이그레이션이 완료되지만 사용자에게 GitHub Enterprise Server액세스 권한을 부여하는 몇 가지 후속 작업이 있습니다.

다음 단계

사용자에게 새 리포지토리에 대한 액세스 권한을 부여하고 사용자 계정과 작업을 조정합니다. GitHub Enterprise Server에서 GHE.com 실시간 마이그레이션 완료을(를) 참조하세요.