CI 구성하기

Turborepo는 Continuous Integration 파이프라인에서 수행해야 하는 빌드, 린트, 테스트 및 기타 모든 task를 가속화합니다. 병렬화와 Remote Caching을 통해 Turborepo는 CI를 극적으로 빠르게 만듭니다.

CI 벤더를 Remote Cache에 연결하고 task를 실행하는 방법의 예제는 CI 가이드를 참조하세요.

Remote Caching 활성화하기

CI에 대해 Remote Caching을 활성화하려면 Turborepo가 Remote Cache에 액세스할 수 있도록 환경 변수를 설정합니다.

환경 변수	설명
`TURBO_TOKEN`	Remote Cache에 액세스하기 위한 Bearer 토큰
`TURBO_TEAM`	리포지토리와 연결된 계정 이름. Vercel Remote Cache를 사용하는 경우 팀의 slug입니다.

turbo를 통해 task를 실행하면 CI가 캐시를 적중하여 파이프라인을 가속화할 수 있습니다.

Remote Cache 호스팅

Vercel의 내장 CI/CD는 설정 없이 관리되는 Vercel Remote Cache에 자동으로 연결됩니다. 다른 CI 벤더를 Vercel Remote Cache에 연결하기 위한 토큰을 가져오려면 Vercel Remote Cache 문서를 참조하세요.

자체 호스팅 Remote Cache 옵션은 Turborepo의 Remote Cache 문서를 참조하세요.

CI에서 task 실행하기

개발 및 CI 머신에 turbo를 전역으로 설치하면 개발부터 배포까지 전체 리포지토리를 실행하는 데 하나의 멘탈 모델을 사용할 수 있습니다. turbo.json에 등록한 task는 CI에서 정확히 동일하게 작동합니다.

task 설정 방법에 대한 자세한 내용은 Task 구성하기 페이지를 참조하세요.
CI에서 task를 실행하는 예제는 CI 가이드를 참조하세요.

진입점 필터링하기

로컬에서 turbo로 작업할 때와 정확히 동일하게 --filter 플래그를 사용하여 task를 필터링할 수 있습니다. 패키지, 디렉토리 및 Git 기록별 필터링이 모두 CI에서 지원됩니다.

CI에서 Git 기록 사용하기

소스 제어 변경 사항을 사용한 필터링은 머신에서 기록을 사용할 수 있는 경우에만 가능합니다. shallow clone을 사용하는 경우 기록을 사용할 수 없습니다.

또한 --affected 플래그를 사용하여 변경 사항이 있는 패키지의 task만 실행할 수 있습니다.

Docker

Docker는 많은 배포 파이프라인의 중요한 부분입니다. Turborepo의 prune 하위 명령은 이미지에서 불필요한 종속성과 코드를 제거하여 경량 이미지를 배포하는 데 도움이 됩니다.

Docker를 사용하여 Turborepo에서 배포하는 방법에 대한 자세한 내용은 전용 Docker 가이드를 참조하세요.

Task 및 기타 불필요한 작업 건너뛰기

영향을 받은 task만 실행하기

--affected 플래그를 사용하여 변경 사항이 있는 task만 실행할 수 있습니다.

Terminal

turbo run build --affected

다음과 같은 상황에서 이 플래그를 사용하려고 할 것입니다:

monorepo의 패키지 전체에서 많은 task를 실행하고 있으며 코드 변경 사항이 있는 패키지의 task만 실행하려는 경우.
Remote Cache를 사용하지 않지만 CI에서 가능한 한 적은 작업을 수행하려는 경우.
Remote Cache를 사용하고 있으며 대규모 리포지토리에 있는 경우. 캐시에서 복원될 task의 양을 최소화하면 네트워크를 통해 전송할 데이터가 줄어들어 캐시 복원이 더 빨라집니다.
이미 고급 필터링 기술 또는 turbo-ignore를 사용하여 --affected와 동일하거나 유사한 동작을 생성하고 있는 경우. 이 새 플래그를 사용하여 스크립팅을 단순화할 기회가 있을 것입니다.
- --affected는 모든 task를 실행하는 것으로 폴백하기 때문에 맞춤형 필터링보다 shallow clone을 더 우아하게 처리할 수 있습니다.

GitHub Actions에서 `--affected` 사용하기

CI/CD 파이프라인은 --affected를 사용하기에 완벽한 곳입니다. --affected를 사용하면 Turborepo는 GITHUB_BASE_REF와 같이 GitHub에서 설정한 환경 변수를 검사하여 GitHub Actions에서 실행 중임을 자동으로 감지할 수 있습니다.

PR의 컨텍스트에서 이는 Turborepo가 PR의 기본 브랜치와 PR의 헤드 브랜치 간에 변경된 패키지를 결정할 수 있음을 의미합니다. 이를 통해 PR의 변경 사항에 영향을 받는 패키지에 대해서만 task를 실행할 수 있습니다.

GITHUB_BASE_REF는 pull_request 및 pull_request_target 이벤트에서 잘 작동하지만 일반 push 이벤트에서는 사용할 수 없습니다. 이러한 경우 GITHUB_EVENT_PATH를 사용하여 커밋과 비교할 기본 브랜치를 결정합니다. force push 및 추가 커밋이 없는 브랜치 푸시에서는 브랜치의 첫 번째 커밋의 부모와 비교합니다.

`turbo-ignore` 사용하기

코드베이스와 CI가 성장함에 따라 더 빠르게 만드는 더 많은 방법을 찾기 시작할 수 있습니다. 캐시를 적중하는 것이 유용하지만 작업을 완전히 건너뛸 수도 있습니다. turbo-ignore를 사용하면 어쨌든 캐시 적중으로 끝날 종속성 설치와 같은 긴 컨테이너 준비 단계를 건너뛸 수 있습니다.

리포지토리 체크아웃하기

리포지토리를 복제하는 것으로 시작합니다. 사용할 복제 깊이에 대한 기록이 있는 복제가 비교에 필요합니다.

Good to know:

기본적으로 turbo-ignore는 부모 커밋을 사용합니다. 더 깊이를 사용자 지정하려면 turbo-ignore 참조를 참조하세요.

패키지 및 task에 대해 `turbo-ignore` 실행하기

기본적으로 turbo-ignore는 현재 작업 디렉토리의 build task를 사용합니다.

다른 task의 변경 사항을 확인하려면 --task 플래그를 사용합니다.
특정 패키지 및 해당 종속성의 변경 사항을 확인하려면 패키지 이름을 인수로 추가합니다.

web 패키지를 인수로 추가하여 web 패키지 및 해당 종속성에 대한 build task의 변경 사항을 확인합니다:

Terminal

npx turbo-ignore web

결과 처리하기

패키지 또는 해당 내부 종속성에서 변경 사항이 감지되면 turbo는 1 상태 코드로 종료됩니다. 변경 사항이 감지되지 않으면 0으로 종료됩니다.

이 상태 코드를 사용하여 CI 파이프라인의 나머지 부분이 수행해야 할 작업을 선택할 수 있습니다. 예를 들어, 1 종료 코드는 종속성을 설치하고 task를 실행하는 것으로 진행해야 함을 의미할 것입니다.

더 고급 사용 사례는 turbo-ignore 참조를 참조하세요.

모범 사례

캐싱에 의존하기

Turborepo의 캐싱 기능을 사용하면 최소한의 복잡성으로 빠른 CI 파이프라인을 생성할 수 있습니다. Remote Caching 및 --filter 플래그를 사용하여 빌드할 패키지를 대상으로 지정하면 Turborepo는 오버헤드가 거의 없이 대규모 monorepo에 대한 변경 감지를 처리합니다.

예를 들어, CI는 다음 두 명령을 실행하여 품질 검사를 빠르게 처리하고 대상 애플리케이션을 빌드할 수 있습니다:

turbo run lint check-types test: 전체 리포지토리에 대한 품질 검사를 실행합니다. 변경되지 않은 패키지는 캐시를 적중합니다.
turbo build --filter=web: turbo.json에 등록한 build task를 사용하여 web 패키지를 빌드합니다. web 패키지 또는 해당 종속성이 변경되지 않은 경우 빌드도 캐시를 적중합니다.

코드베이스가 확장됨에 따라 CI를 최적화할 더 구체적인 기회를 찾을 수 있지만 캐싱에 의존하는 것이 시작하기에 좋은 곳입니다.

CI에서 전역 `turbo`

전역 turbo를 사용하면 CI 워크플로우에서 편리하며 CI에 특정한 명령을 쉽게 실행하고 자동 Workspace 범위 지정을 활용할 수 있습니다.

그러나 일부 경우에는 패키지 관리자로 패키지를 설치하기 전에 turbo 명령 또는 turbo를 사용하는 스크립트를 실행할 수 있습니다. 이에 대한 한 가지 예는 turbo prune을 사용하여 Docker 이미지를 생성하는 것입니다. 이 상황에서 전역 turbo는 해당 버전의 바이너리가 아직 설치되지 않았기 때문에 package.json의 버전을 사용할 수 없습니다.

이러한 이유로 주요 버전 내에서 중단 변경이 도입되지 않으므로 CI에서 turbo의 전역 설치를 package.json의 주요 버전에 고정하는 것을 권장합니다. 또한 정확한 버전을 고정하여 안정성을 추가로 선택할 수 있지만 패치 릴리스에서 버그 수정을 받기 위해 유지 관리 부담을 감수해야 합니다.

CI에서 `turbo run` 사용하기

turbo run은 Turborepo에서 작업할 때 가장 일반적으로 사용하는 명령이므로 편의를 위해 turbo로 별칭이 지정됩니다. 이는 로컬에서 작업하기에 좋지만 turbo prune 및 turbo generate와 같은 turbo에 대한 다른 하위 명령이 있습니다.

우리는 항상 turbo를 개선하기 위해 노력하고 있으므로 향후 더 많은 하위 명령을 추가할 수 있습니다. 이러한 이유로 CI에서 turbo run을 사용하여 이름 충돌을 방지할 수 있습니다.

예를 들어, CI 파이프라인에 turbo deploy 명령이 있는 경우 turbo CLI에 직접 빌드된 잠재적인 deploy 하위 명령과 충돌할 수 있습니다. 이를 피하려면 CI 파이프라인에서 대신 turbo run deploy를 사용하세요.