> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Mastra 플랫폼의 GitHub 통합

GitHub 통합은 Mastra 플랫폼 프로젝트를 GitHub 저장소에 연결합니다. 저장소에 변경 사항을 푸시하면 Studio 및 서버가 자동으로 배포됩니다.

:::참고 통합은 GitHub.com에서 호스팅되는 리포지토리에서만 작동합니다. 자체 호스팅 GitHub Enterprise 인스턴스는 현재 지원되지 않습니다. :::

저장소가 연결된 후 플랫폼은 다음을 수행합니다.

- 구성된 분기에 푸시할 때마다 Studio 및 서버를 빌드하고 배포합니다.
- 템플릿에서 생성된 프로젝트에 대한 관리형 데이터베이스와 게이트웨이 API 키를 프로비저닝합니다.
- 배포할 때마다 표면 커밋, 분기 및 끌어오기 요청 컨텍스트가 표시됩니다.
- 검사가 실행될 때 빌드 상태를 GitHub에 다시 보고하고 실시간 상태 배지와 인라인 로그가 포함된 프로젝트 대시보드에 보고합니다.

## GitHub 통합을 사용하는 경우

다음 중 하나를 원할 경우 GitHub 통합을 선택하십시오.

- 푸시하여 배포`main` 또는 Studio와 Server에 각각 별도의 브랜치를 사용하는 경우를 포함하여 다른 모든 브랜치에 연결할 수 있습니다.
- 새로운 리포지토리, 관리형 데이터베이스 및 게이트웨이 API 키를 포함하여 Mastra 템플릿에서 프로젝트를 스캐폴드하는 관리형 온보딩 흐름입니다.
- 분류를 위해 플랫폼 대시보드 내부의 풀 요청 및 커밋 컨텍스트.

CLI 흐름(`mastra studio deploy` and `mastra server deploy`)은 임시 배포와 GitHub 이외의 CI Provider에서 계속 사용할 수 있습니다. 자세한 내용은 [Studio](https://mastra.zisheng.pro/ko/docs/mastra-platform/studio) and [Server](https://mastra.zisheng.pro/ko/docs/mastra-platform/server) for the CLI-only path.

## Mastra GitHub 앱 설치

통합은 Mastra GitHub 앱에 의해 구동됩니다.

앱은 저장소 콘텐츠를 읽고 수신합니다.`push` 이벤트가 구성된 브랜치에서 발생하면 배포합니다. 배포 상태는 검사 실행으로 다시 기록됩니다.

1. 에서[Mastra platform dashboard](https://projects.mastra.ai)에서 조직 설정을 여세요. 해당 페이지에는 **GitHub App** section.

2. 선택하다**Install GitHub App** 을 선택한 다음 설치할 GitHub 계정 또는 조직을 선택하세요.

   GitHub 조직을 소유하지 않은 경우 GitHub는 보류 중인 조직을 생성합니다.**installation request** 이 생성되며 관리자의 승인이 필요합니다. 대시보드에서는 대기 중인 요청과 완료된 설치를 함께 추적합니다.

3. 앱이 액세스할 수 있는 저장소를 선택합니다. 특정 저장소로 범위를 지정하거나 계정의 모든 저장소에 대한 액세스 권한을 부여할 수 있습니다.

   GitHub의 앱 설정에서 언제든지 저장소 액세스를 취소하거나 변경할 수 있습니다.

:::참고 나중에 GitHub가 앱의 필수 권한을 업데이트하면 대시보드에**outdated permissions** 경고와 승인 링크가 표시됩니다. 저장소 작업은 `403` until an admin re-approves. :::

### 설치 요청 대기 중

관리자가 아닌 사람이 조직에 앱을 요청하면 해당 요청은 조직 관리자가 GitHub.com에서 승인할 때까지 보류 상태로 유지됩니다. 대시보드:

- 활성 설치 옆에 보류 중인 요청을 나열합니다.
- 동일한 사용자가 한 번에 여러 GitHub 계정에 대한 액세스를 요청할 수 있습니다.
- 페이지를 열 때 GitHub에 대해 보류 상태를 조정하여 관리자가 거부했거나 요청자가 철회한 요청을 제거합니다.

보류 중인 요청을 취소하려면 다음을 선택하세요.**Cancel** next to it in the dashboard.

## 템플릿에서 프로젝트 만들기

템플릿은 시작하는 가장 빠른 방법입니다. 플랫폼은 Mastra 템플릿에서 새 저장소를 생성하고 이를 새로운 프로젝트에 연결하고 템플릿이 선언하는 관리형 데이터베이스를 프로비저닝하고 첫 번째 배포를 실행합니다.

1. 대시보드에서**Create project** and choose **Start from a template**.

2. 템플릿을 선택하고 새 저장소를 소유한 GitHub 계정을 선택하세요. 저장소의 이름을 지정하고 비공개인지 여부를 선택합니다.

3. 템플릿의 관리형 데이터베이스 요구 사항을 구성합니다. 템플릿은 필수 데이터베이스(예: Turso 또는 Neon)를 선언할 수 있으며 요구 사항에 따라 공급자와 지역을 선택합니다.

4. 템플릿별 환경 변수(예: AI 공급자 API 키)를 추가합니다. 플랫폼 씨앗`MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` 을 자동으로 설정하므로 Gateway와 통신하는 템플릿 코드가 첫 배포부터 작동합니다.

5. 선택하다**Create project**. The platform creates the repository, writes a `.mastra-project.json` 구성 파일을 저장소에 추가하고 관리형 데이터베이스를 프로비저닝한 다음, 최초 Studio 및 Server 배포를 시작합니다.

초기 배포는 시작되기 전에 관리형 데이터베이스가 프로비저닝을 완료할 때까지 기다리므로 템플릿의 첫 번째 빌드에서는 데이터베이스 연결 환경 변수가 표시됩니다.

## 기존 저장소 연결

GitHub 리포지토리에 이미 Mastra 프로젝트가 있는 경우 이 흐름을 사용하세요.

1. 대시보드에서**Create project** and choose **Connect an existing repository**, or open an existing project and select **Link repository** from the project settings.

2. 설치를 선택한 다음 저장소를 선택합니다. 리포지토리 검색은 해당 설치에서 앱이 액세스할 수 있는 모든 리포지토리에서 작동합니다.

3. Studio 및 Server 배포 분기를 선택합니다. 두 대상 모두 리포지토리의 기본 분기로 기본 설정되며 분기를 공유하거나 다른 분기를 사용할 수 있습니다.

   프로젝트에 대해 Studio 또는 Server를 비활성화할 수 있습니다. 매뉴얼**Deploy from GitHub** 서랍에서는 둘 다 구성된 경우 기본적으로 두 대상을 모두 선택합니다.

4. 선택하다**Link repository**를 선택합니다. 플랫폼은 저장소에 이미 다른 프로젝트를 가리키는 `.mastra-project.json` 파일이 있는지 검증합니다. 해당 파일이 있으면 대시보드에서 경고하고 **Overwrite** option that replaces the file on link.

연결 후 구성된 분기에 대한 다음 푸시는 배포를 트리거합니다.

### `.mastra-project.json`갈등

플랫폼은 다음을 씁니다.`.mastra-project.json` 파일을 연결된 모든 저장소에 추가하여 프로젝트를 식별합니다. 이러한 파일이 이미 있는 저장소를 연결하면 대시보드가 제출 전에 파일 내용을 확인합니다:

- **없어진**: 플랫폼은 링크에 파일을 생성합니다.
- **어울리는**: 파일은 이미 연결 중인 프로젝트를 가리키므로 변경할 필요가 없습니다.
- **서로 싸우는**: 파일이 다른 프로젝트를 가리킵니다. 파일을 취소하거나 명시적으로 덮어쓸 수 있습니다.

보다[Configuration](https://mastra.zisheng.pro/ko/docs/mastra-platform/configuration) for the file's schema.

## 푸시하여 배포

리포지토리가 연결된 후 구성된 브랜치에 푸시할 때마다 배포가 트리거됩니다.

- 푸시**Studio branch** triggers a Studio deploy.
- 푸시**Server branch** triggers a Server deploy.
- 두 대상이 모두 분기를 공유하는 경우 한 번의 푸시로 두 배포가 동시에 트리거됩니다.

각 배포에는 커밋 SHA, 분기 및 (사용 가능한 경우) 커밋을 도입한 풀 요청 번호가 포함됩니다. 빌드는 플랫폼 내에서 실행되고 커밋에 대한 검사가 실행될 때 상태를 GitHub에 다시 보고합니다.

배포 대상당 한 번에 하나의 빌드만 실행됩니다. 빌드가 진행되는 동안 새 푸시가 도착하면 플랫폼은 동일한 대상에 대해 대기 중인 이전 빌드를 취소하고 최신 빌드를 실행합니다. Studio 및 서버 빌드는 독립적으로 추적되므로 두 대상이 모두 구성되면 병렬로 실행될 수 있습니다.

### 수동 GitHub 배포

푸시하지 않고도 대시보드에서 배포를 트리거할 수도 있습니다. 프로젝트를 열고 선택하세요.**Deploy from GitHub**에서 대상(Studio, Server 또는 둘 다)과 브랜치를 선택한 후 제출하세요. 플랫폼은 해당 브랜치의 최신 커밋을 대상으로 배포를 실행하고 트리거를 **GitHub Workflow** deploy.

## 배포 추적

프로젝트가 템플릿에서 생성되거나 저장소에 링크된 후**Setup** 페이지에는 배포 대상별로 하나의 행이 표시됩니다. 각 행에서는:

- 배포가 완료될 때까지 배포를 폴링하는 실시간 상태 배지를 표시합니다.
- 배포 ID를 통해 배포 세부정보 페이지로 연결됩니다.
- 노출하다**Show logs** 토글을 사용하여 빌드 및 런타임 로그를 인라인으로 스트리밍할 수 있습니다. 배포가 활성 상태인 동안 Server 로그는 3초마다 폴링됩니다.

## 권한 및 철회

저장소에서 배포를 중지하려면 다음 중 하나를 수행합니다.

- **저장소 연결 해제**의 프로젝트에서**Project settings → Repository**합니다. 프로젝트의 기록은 유지되며 나중에 다른 저장소를 다시 연결할 수 있습니다.
- **저장소 액세스 제거**GitHub.com의 Mastra GitHub 앱용. 기존 배포는 계속 실행되지만 새 푸시가 배포를 트리거하지 않습니다.
- **GitHub 앱 제거**GitHub 계정에서. 이렇게 하면 해당 계정의 모든 저장소에 대한 액세스가 제거됩니다.

GitHub가 앱의 설치 토큰을 취소하거나 순환하는 경우 리포지토리 읽기는 반환됩니다.`github_app_permissions_outdated` 오류가 발생하며 대시보드에서 관리자에게 권한을 다시 승인하라는 메시지가 표시됩니다.

## 관련된

- [마스트라 플랫폼 개요](https://mastra.zisheng.pro/ko/docs/mastra-platform/overview)
- [Mastra 플랫폼의 스튜디오](https://mastra.zisheng.pro/ko/docs/mastra-platform/studio)
- [Mastra 플랫폼의 서버](https://mastra.zisheng.pro/ko/docs/mastra-platform/server)
- [구성](https://mastra.zisheng.pro/ko/docs/mastra-platform/configuration)