GitHub 통합

Git 리포지토리는 대부분의 소프트웨어 프로젝트에서 핵심입니다. Tuist는 GitHub와 통합하여 풀 리퀘스트에서 바로 Tuist 인사이트를 제공하고, 기본 브랜치 동기화와 같은 설정 작업을 줄여줍니다.

설정#

조직의 Integrations 탭에서 Tuist GitHub 앱을 설치해야 합니다:

GitHub에서 직접 앱을 설치할 수도 있습니다. 필요하면 Tuist에 로그인하고, Tuist가 설치 접근 권한을 확인할 수 있도록 GitHub 앱을 승인한 후 연결할 Tuist 조직을 선택하세요. 앱을 설치하는 GitHub 조직(또는 개인 GitHub 계정)의 소유자여야 합니다. 관리 중인 Tuist 조직과 개인 Tuist 계정만 표시됩니다. 계정이 하나뿐이면 Tuist가 선택 화면 없이 자동으로 연결합니다. Tuist에서 시작하면 조직이 이미 선택되어 있어 이 단계는 건너뜁니다.

그다음 GitHub 리포지토리と Tuist 프로젝트 간 프로젝트 연결을 추가할 수 있습니다:

앱을 설치한 후에는 대시보드 없이도 프로젝트를 연결할 수 있습니다:

• CLI:tuist project repository connect owner/name, 그리고 링크를 제거하려면 tuist project repository disconnect를 사용하세요.
• REST API:PUT 및 DELETE를 /api/projects/{account_handle}/{project_handle}/vcs-connection 엔드포인트에 호출하세요.
• Model Context Protocol:connect_project_repository 및 disconnect_project_repository 도구를 사용하세요.

리포지토리는 GitHub 앱 설치가 접근할 수 있어야 하며, 프로젝트는 리포지토리의 기본 브랜치를 사용합니다. 계정 토큰에는 project:admin:write 스코프가 필요합니다.

GitHub Enterprise Server#

Tuist는 자체 호스팅된 GitHub Enterprise Server(GHES) 인스턴스와도 통합됩니다. GitHub 통합 카드에서 Enterprise server 탭으로 전환하고 GHES 기본 URL(예: https://github.example.com)을 입력한 후 설치를 클릭하세요.

GitHub 앱은 단일 GitHub 인스턴스 범위로 제한되므로, Tuist는 github.com용 앱을 GHES에서 재사용할 수 없습니다. 대신 설치 버튼을 누르면 GitHub의 앱 매니페스트 흐름이 진행됩니다. GHES는 관리자가 인스턴스에 새로운 Tuist 앱을 등록하도록 안내한 후 새 앱의 자격 증명을 Tuist에 전달합니다. Tuist는 해당 자격 증명을 설치별로 암호화하여 저장하고, 이후 모든 API 호출, 웹후크 서명, 리포지토리 링크에 사용합니다.

추가 Tuist 서버 구성은 필요하지 않습니다. 매니페스트 흐름이 모든 것을 자동으로 생성하고 프로비저닝합니다.

앱 권한 및 웹후크 이벤트#

Tuist는 PR 댓글 및 번들 크기 확인을 위해 다음 리포지토리 권한이 필요합니다:

Tuist는 check_run 웹후크 이벤트를 사용하여 번들 크기 확인 작업을 처리합니다. 매니페스트 흐름이 이 구독을 자동으로 구성합니다.

자체 호스팅 Tuist 서버와 함께 github.com에서 앱을 수동으로 설정하려면 자체 호스팅 가이드를 참조하세요.

브라우저 및 API URL 분리#

엔지니어가 내부 호스트명으로 GitHub Enterprise에 접근하고 서드파티 서비스가 외부 프록시를 사용하는 경우, 설치 클릭 전에 두 주소를 모두 구성하세요:

API URL은 /api/v3 또는 프록시가 노출하는 해당 경로를 포함한 전체 REST API 기본 URL입니다. Tuist는 명시적 API URL에 /api/v3를 추가하지 않습니다. 브라우저와 Tuist 모두에서 하나의 호스트명으로 작동한다면 비워 두세요. 기존 연결은 계속 <Server URL>/api/v3을 사용합니다.

두 주소 모두 동일한 GitHub Enterprise 인스턴스로 라우팅되어야 합니다. 브라우저는 서버 URL에만 도달하면 되며 API 프록시는 필요하지 않습니다. Tuist 서버는 API URL에만 도달하면 되며 내부 브라우저 호스트명은 필요하지 않습니다.

외부 프록시의 경우:

• Tuist 서버가 신뢰하는 인증서와 공개 IP 주소로 해결되는 공개 DNS를 사용하는 HTTPS를 사용하세요. API URL 재정의는 Tuist의 사설 IP/SSRF 보호를 우회하지 않습니다. 재정의 대상은 github.com 또는 *.github.com 엔드포인트가 아닌 Enterprise 인스턴스여야 합니다.
• 모든 Tuist 아웃바운드 IP 주소를 허용 목록에 추가하세요.
• Tuist가 사용하는 REST API 엔드포인트(POST /api/v3/app-manifests/{code}/conversions, POST /api/v3/app/installations/{installation_id}/access_tokens 포함)와 댓글 및 체크용 리포지토리 API 엔드포인트를 전달하세요. 이는 GitHub의 업스트림 경로이므로, 프록시가 다른 접두사를 노출하는 경우 이를 번역하세요.
• HTTP 리다이렉트나 상호작용형 로그인 페이지 없이 GitHub로 요청을 전달하세요. Tuist는 Enterprise API 리다이렉트를 자동으로 따르지 않으므로 공개 IP 확인을 우회할 수 없습니다. 매니페스트 변환 엔드포인트는 Tuist가 앱 자격 증명을 갖기 전인 설정 중에 도달 가능해야 합니다. GitHub Actions 로그 다운로드가 예외입니다: Tuist는 HTTPS에서만 서명된 아카이브 리다이렉트를 따르며, 모든 대상을 공개 IP로 확인하고 고정하며, 설치 토큰을 전달하지 않습니다.

GitHub는 내부 호스트명을 사용하여 페이지네이션 링크를 반환할 수 있습니다. Tuist는 구성된 GitHub 인스턴스의 링크를 API URL로 재베이스하여 프록시의 경로 접두사를 유지하며, 관련 없는 출처로의 링크는 거부됩니다.

별도로, GitHub는 웹후크를 https://tuist.dev/webhooks/github(또는 자체 호스팅 Tuist 서버의 /webhooks/github)로 전달할 수 있어야 합니다. 엔지니어는 브라우저 콜백을 완료하기 위해 Tuist로 돌아갈 수 있어야 합니다. API URL은 두 대상 모두 변경하지 않습니다.

조직 관리자는 통합 카드의 Save API URL을 사용하여 기존 Enterprise 통합의 API URL을 변경하거나 지울 수 있습니다. 앱 재설치나 프로젝트 재연결이 필요하지 않습니다. 지우면 <Server URL>/api/v3로 복원됩니다. 저장은 URL 형식을 검증하지만 프록시 연결성은 검증하지 않습니다. 설치 조회가 캐시되므로 웹후크 처리가 변경된 주소를 사용하는 데 최대 1분이 걸릴 수 있으며, 이미 진행 중인 요청은 이전 주소를 계속 사용할 수 있습니다.

풀/머지 리퀘스트 댓글#

GitHub 앱은 최신 프리뷰 또는 테스트 링크를 포함한 PR 요약을 담은 Tuist 실행 보고서를 게시합니다:

Tuist는 결과가 도착함에 따라 하나의 댓글을 업데이트합니다. Gradle 빌드는 각 루트 프로젝트와 요청된 작업 세트별로 별도로 표시되며, 동일한 작업을 다시 실행하면 해당 호출의 이전 결과가 대체됩니다. 전체 빌드 기록은 Tuist에서 계속 확인할 수 있습니다.

댓글은 기본적으로 활성화되어 기존 통합의 보고를 유지합니다. 프로젝트에서 댓글을 끄거나 다시 켜려면 Project Settings → Integrations을 열고 GitHub → Run report comments를 토글하세요. 각 프로젝트에는 고유한 설정이 있으며, 리포지토리 연결은 조직 설정에서 관리됩니다.

댓글을 비활성화해도 빌드 또는 테스트 업로드, GitHub Actions 작업 요약, 리포지토리 연결 또는 기타 GitHub 통합 기능이 비활성화되지 않습니다. 기존 댓글은 삭제되지 않습니다.

GitHub Actions 작업 요약#

Tuist CLI와 Gradle 플러그인은 테스트 및 빌드 결과를 GitHub Actions의 작업 요약에 기록합니다. 요약에는 불안정한 테스트 및 번들 크기 차이 등 더 풍부한 인사이트를 제공하는 Tuist의 전체 보고서 링크가 포함됩니다.

Gradle의 경우, 성공적으로 업로드된 각 빌드 또는 테스트 보고서는 gradle/actions/setup-gradle과 같은 도구가 작성한 다른 콘텐츠를 유지하면서 자체 요약을 추가합니다. 이 기능은 작업 요약 지원을 포함하는 플러그인 버전이 필요합니다. 이전 Gradle 플러그인 버전은 GitHub 앱의 PR 댓글을 통해서만 보고합니다. 작업 요약에는 GitHub 앱 연결이 필요하지 않으며, Run report comments를 비활성화해도 영향을 받지 않습니다.

GitHub Actions 요약 대상이 사용 가능한 경우, Gradle은 uploadInBackground이 활성화되어 있더라도 업로드 및 요약을 기다린 후 종료합니다. GitHub는 워크플로우 단계가 끝나면 요약을 캡처합니다.

이는 머지 큐와 함께 사용할 때 특히 유용합니다. 머지 큐 실행은 풀 리퀘스트에 연결되지 않으므로 댓글이 게시되지 않지만, 작업 요약에는 여전히 결과가 표시됩니다.