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 and Server for the CLI-only path.

Mastra GitHub 앱 설치

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

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

1. 에서Mastra platform dashboard에서 조직 설정을 여세요. 해당 페이지에는 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 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 오류가 발생하며 대시보드에서 관리자에게 권한을 다시 승인하라는 메시지가 표시됩니다.

관련된

• 마스트라 플랫폼 개요
• Mastra 플랫폼의 스튜디오
• Mastra 플랫폼의 서버
• 구성