GraphQL을 사용하여 GitLab에서 GitHub Enterprise Cloud로 리포지토리 마이그레이션

참고

마이그레이션을 수행하는 데 사용할 GL2GH extension of the GitHub CLI 수도 있습니다. GitLab에서 GitHub 마이그레이션 이해을(를) 참조하세요.

0단계: GitHub GraphQL API를 사용할 준비하기

GraphQL 쿼리를 만들려면 사용자 고유의 스크립트를 작성하거나 Insomnia와 같은 HTTP 클라이언트를 사용해야 합니다.

인증 방법을 포함하여 GitHub GraphQL API를 시작하는 방법에 대한 자세한 내용은 GraphQL을 사용하여 통화 구성을(를) 참조하세요.

모든 GraphQL 쿼리를 마이그레이션의 대상으로 보냅니다. 데이터 보존 기능을 갖춘 GitHub Enterprise Cloud로 마이그레이션하는 경우 엔터프라이즈의 하위 도메인인 GHE.com에 대한 엔드포인트로 쿼리를 보내세요.

1단계: 마이그레이션 대상에 대한 `ownerId` 가져오기

GitHub Enterprise Cloud의 조직 소유자는 마이그레이션된 리포지토리를 소유하려는 조직의 조직 ID라고도 하는 GetOrgInfo 쿼리를 ownerId에 반환합니다. 마이그레이션 대상을 식별하려면 ownerId이(가) 필요합니다.

`GetOrgInfo` 쿼리

query(
  $login: String!
){
  organization (login: $login)
  {
    login
    id
    name
    databaseId
  }
}

쿼리 변수	설명
`login`	조직 이름

`GetOrgInfo` 응답

{
  "data": {
    "organization": {
      "login": "Octo",
      "id": "MDEyOk9yZ2FuaXphdGlvbjU2MTA=",
      "name": "Octo-org",
      "databaseId": 5610
    }
  }
}

이 예제에서는 MDEyOk9yZ2FuaXphdGlvbjU2MTA=이(가) 다음 단계에서 사용할 조직 ID 또는 ownerId입니다.

2단계: 마이그레이션할 위치 식별

createMigrationSource 쿼리를 사용하여 마이그레이션 원본을 설정할 수 있습니다. GetOrgInfo 쿼리에서 수집된 조직 ID 또는 조직 ID를 ownerId에 제공해야 합니다.

마이그레이션 원본은 GitLab 인스턴스입니다.

`createMigrationSource` 변형

mutation createMigrationSource($name: String!, $url: String!, $ownerId: ID!) {
  createMigrationSource(input: {name: $name, url: $url, ownerId: $ownerId, type: GITLAB}) {
    migrationSource {
      id
      name
      url
      type
    }
  }
}

GitLab 인스턴스의 전체 URL(예: 또는 https://gitlab.example.com.)로 https://gitlab.com 설정합니다url. GITLAB에 type를 사용해야 합니다.

쿼리 변수	설명
`name`	마이그레이션 원본의 이름입니다. 이 이름은 사용자 고유의 참조용이므로, 모든 문자열을 사용할 수 있습니다.
`ownerId`	GitHub Enterprise Cloud에 있는 조직의 조직 ID입니다.

`createMigrationSource` 응답

{
  "data": {
    "createMigrationSource": {
      "migrationSource": {
        "id": "MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA",
        "name": "GitLab Source",
        "url": "https://gitlab.com",
        "type": "GITLAB"
      }
    }
  }
}

이 예제에서 MS_kgDaACQxYmYxOWU4Yi0wNzZmLTQ3NTMtOTdkZC1hNGUzZmYxN2U2YzA은(는) 이후 단계에서 사용할 마이그레이션 원본 ID입니다.

3단계: 마이그레이션 보관 파일 생성 및 호스트

GitLab에서 마이그레이션은 보관 기반입니다. 마이그레이션 GitHub Enterprise Importer 중에 GitLab 인스턴스에 연결하는 대신 GitLab 프로젝트에서 생성한 마이그레이션 보관 파일을 가져옵니다. GitLab 보관 파일은 Git 원본과 리포지토리의 메타데이터를 모두 포함하는 단일 파일입니다.

마이그레이션을 시작하기 전에 다음을 수행해야 합니다.

마이그레이션하려는 GitLab 프로젝트에 대한 마이그레이션 보관 파일을 생성합니다.
액세스할 수 있는 URL GitHub Enterprise Cloud 에서 보관 파일을 호스트합니다.

이 URL은 다음 단계에서 값으로 gitArchiveUrl 제공합니다.

마이그레이션 보관 파일 생성

GitLab 프로젝트 내보내기 API 를 사용하여 마이그레이션하려는 프로젝트를 내보냅니다. 사용하는 토큰에는 프로젝트를 내보낼 api 수 있는 권한이 있는 범위와 역할이 있어야 합니다. 자세한 내용은 GitLab에서 GitHub 마이그레이션에 대한 액세스 관리을(를) 참조하세요.

다음 요청에서 환경 변수를 GITLAB_PATGitLab에서 GitHub 마이그레이션에 대한 액세스 관리에서 만든 토큰으로 설정합니다. GitLab 인스턴스의 호스트(예: )로 gitlab.com바꾸고 프로젝트의 URL로 인코딩된 경로로 바 GROUP%2FPROJECT 꿉 GITLAB-SERVER 니다. 예를 들어 프로젝트는 acme-group/my-project .로 acme-group%2Fmy-project인코딩됩니다. 중첩된 하위 그룹의 경우 전체 경로(예: parent-group%2Fsubgroup%2Fmy-project.)를 포함합니다.

내보내기를 예약합니다.

curl --request POST \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"

내보내기의 상태를 확인합니다. 가 될 때까지 export_status 이 요청을 반복합니다 finished.

curl --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export"

보관 파일을 다운로드합니다.

curl --location \
  --header "PRIVATE-TOKEN: $GITLAB_PAT" \
  --output archive.tar.gz \
  "https://GITLAB-SERVER/api/v4/projects/GROUP%2FPROJECT/export/download"

보관 파일 호스팅

액세스할 수 있는 URL GitHub Enterprise Cloud 에서 보관 파일을 호스트해야 합니다. 보관 파일을 외부 Blob Storage 공급자에 GitHub-owned blob storage 업로드하거나 사용할 수 있습니다. 외부 공급자에 대한 자세한 내용은 Blob Storage 구성을 참조하세요.

보관 파일을 GitHub-owned blob storage업로드하려면 조직의 GitHub Enterprise Cloud데이터베이스 ID가 필요합니다. 응답의 필드에서 이 ID id 를 가져오려면 조직의 이름으로 바꿉 ORGANIZATION 니다.

curl --header "Authorization: Bearer YOUR-TOKEN" \
  "https://api.github.com/orgs/ORGANIZATION"

참고

마이그레이션하는 GHE.com경우 다음과 같이 엔터프라이즈 하위 도메인에 대한 기본 API URL로 https://api.https://api.github.com바꿉 octocorp.ghe.com 니다.

요청으로 보관 파일을 POST 업로드하고 조직의 데이터베이스 ID로 바꿔 ORGANIZATION-ID 서 업로드합니다. 이 요청은 최대 100MiB의 보관에 대해 작동합니다. 더 큰 보관 파일의 경우 외부 Blob Storage 공급자를 사용합니다.

curl --request POST \
  --header "Authorization: Bearer YOUR-TOKEN" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @archive.tar.gz \
  "https://uploads.github.com/organizations/ORGANIZATION-ID/gei/archive?name=archive.tar.gz"

참고

마이그레이션하는 GHE.com경우 다음과 같이 엔터프라이즈 하위 도메인에 대한 업로드 호스트로 uploads.octocorp.ghe.com바꿉 uploads.github.com 니다.

응답에는 형식gei://archive/GUID이 uri 포함됩니다. 다음 단계에서 이 값을 로 gitArchiveUrl 사용합니다.

{
  "guid": "ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "node_id": "MA_kgDaACRmZjdiMWEyNS1hYTEwLTQxYTktOGU0Mi1mMTcwMzA0YjFjMGQ",
  "name": "archive.tar.gz",
  "size": 7103,
  "uri": "gei://archive/ff7b1a25-aa10-41a9-8e42-f170304b1c0d",
  "created_at": "2024-11-13T12:35:45.761-08:00"
}

4단계: 리포지토리 마이그레이션 시작

마이그레이션을 시작하면 단일 리포지토리와 함께 제공되는 데이터가 사용자가 식별하는 새로운 GitHub 리포지토리로 마이그레이션됩니다.

동일한 원본 조직에서 한 번에 여러 리포지토리를 이동하려는 경우 여러 마이그레이션을 큐에 대기시킬 수 있습니다. 최대 5개까지의 리포지토리 마이그레이션을 동시에 실행할 수 있습니다.

`startRepositoryMigration` 변형

mutation startRepositoryMigration (
  $sourceId: ID!,
  $ownerId: ID!,
  $sourceRepositoryUrl: URI!,
  $repositoryName: String!,
  $continueOnError: Boolean!,
  $accessToken: String!,
  $githubPat: String!,
  $gitArchiveUrl: String!,
  $targetRepoVisibility: String!
){
  startRepositoryMigration( input: {
    sourceId: $sourceId,
    ownerId: $ownerId,
    repositoryName: $repositoryName,
    continueOnError: $continueOnError,
    accessToken: $accessToken,
    githubPat: $githubPat,
    targetRepoVisibility: $targetRepoVisibility,
    gitArchiveUrl: $gitArchiveUrl,
    sourceRepositoryUrl: $sourceRepositoryUrl,
  }) {
    repositoryMigration {
      id
      migrationSource {
        id
        name
        type
      }
      sourceUrl
    }
  }
}

쿼리 변수	설명
`sourceId`	마이그레이션 원본 `id`이(가) `createMigrationSource` 변경에서 반환되었습니다.
`ownerId`	GitHub Enterprise Cloud에 있는 조직의 조직 ID입니다.
`repositoryName`	GitHub Enterprise Cloud에서 조직이 소유한 리포지토리 내의 현재 사용되지 않는 사용자 지정 고유 리포지토리 이름입니다. 마이그레이션이 완료되었거나 중지되었을 경우, 오류 로깅 문제가 이 리포지토리에 생성됩니다.
`continueOnError`	마이그레이션이 실패하지 않는 오류가 발생할 경우, 마이그레이션을 계속할 수 있도록 하는 마이그레이션 설정입니다. `true` 또는 `false`이어야 합니다. Importer에서 Git 원본을 이동할 수 없거나 Importer이(가) 연결을 끊고 마이그레이션을 완료하기 위해 다시 연결할 수 없는 한 마이그레이션이 계속되도록 `continueOnError`을(를) `true`(으)로 설정하는 것이 좋습니다.
`githubPat`	personal access token의 대상 조직에 대한 GitHub Enterprise Cloud입니다.
`accessToken`	원본에 대한 personal access token입니다.
`targetRepoVisibility`	새로운 리포지토리의 표시 여부 변경 `private`, `public` 또는 `internal`여야 합니다. 설정하지 않은 경우, 리포지토리가 프라이빗으로 마이그레이션됩니다.

| gitArchiveUrl | GitHub Enterprise Cloud이전 단계에서 생성한 마이그레이션 보관 파일에 액세스할 수 있는 URL입니다. GitLab 마이그레이션은 Git 원본과 메타데이터를 모두 포함하는 단일 보관 파일을 사용하므로 별도의 metadataArchiveUrl보관 파일을 제공할 필요가 없습니다.

| sourceRepositoryUrl | 형식 https://GITLAB-SERVER/{group}/{project}을 사용하여 GitLab에 있는 원본 리포지토리의 URL입니다. 중첩된 하위 그룹의 경우 전체 경로(예: https://GITLAB-SERVER/{parent-group}/{subgroup}/{project}.)를 포함합니다. GitHub Enterprise Cloud 는 마이그레이션 중에 이 URL에 연결하지 않습니다. 참조용으로 기록됩니다.

GitLab 마이그레이션은 보관 기반 GitHub Enterprise Cloud 이므로 마이그레이션 중에 GitLab에 연결하지 않습니다. 변수는 accessToken 변형에 필요하지만 사용되지 않으므로 다음과 같은 자리 표시자 값으로 not-used설정할 수 있습니다.

personal access token 요구 사항은 GitLab에서 GitHub 마이그레이션에 대한 액세스 관리을 참조하세요.

다음 단계에서는 startRepositoryMigration 변형에서 반환된 마이그레이션 ID를 사용하여 마이그레이션 상태를 검사합니다.

5단계: 마이그레이션 상태 확인

마이그레이션 오류를 감지하고 마이그레이션이 작동하는지 확인하려면 getMigration 쿼리를 사용하여 마이그레이션 상태를 검사할 수 있습니다. getMigrations(으)로 여러 마이그레이션의 상태를 검사할 수도 있습니다.

getMigration 쿼리는 상태를 반환하여 마이그레이션이 queued, in progress, failed 또는 completed일지 알려줍니다. 마이그레이션에 실패한 경우 Importer은(는) 실패의 원인을 제공합니다.

`getMigration` 쿼리

query (
  $id: ID!
){
  node( id: $id ) {
    ... on Migration {
      id
      sourceUrl
      migrationSource {
        name
      }
      state
      failureReason
    }
  }
}

쿼리 변수	설명
`id`	`startRepositoryMigration`변형이 반환된 `id` 마이그레이션입니다.

6단계: 마이그레이션 유효성 검사 및 오류 로그 검사

마이그레이션이 완료되면, 마이그레이션 로그 리포지토리를 검사하는 것이 좋습니다. 이 문제는 대상 리포지토리의 GitHub에서 생성됩니다.

"마이그레이션 로그"라는 제목의 문제 스크린샷. 문제의 두 번째 주석에 마이그레이션에 대한 로그가 포함됩니다.

마지막으로, 마이그레이션된 리포지토리에서 건전성 검사를 검토하는 것이 좋습니다.

추가 읽기

후속 작업

GraphQL을 사용하여 GitLab에서 GitHub Enterprise Cloud로 리포지토리 마이그레이션

이 기사에서