Jenkins Mac Agent 디스크 공간 부족은 먼저 작업 공간, Xcode 구성 요소, 빌드 산출물 가운데 어디가 차지하는지 확인한 뒤 해당 항목만 정리해야 합니다. 정리 후에도 경고가 반복되면 실제 작업 기록을 바탕으로 정리 정책이나 맥 CI 노드 운영 방식을 조정하세요.
기업 IT 담당자: 디스크 경고가 빌드 안정성에 영향을 주는지 판단해야 하는 경우에 적합합니다. 플랫폼 엔지니어: Jenkins Mac Agent와 작업 공간, Xcode 환경을 관리하는 경우에 참고하세요. 기술 총괄 및 개발 생산성 담당자: 정리 절차를 개선할지 맥 자원을 조정할지 결정할 때 활용할 수 있습니다.
먼저 디스크 경고와 빌드 실패를 분리하세요
디스크 사용률 경고, 파일 쓰기 실패, Jenkins 작업 실패는 같은 상태가 아닙니다. 저장 공간에 경고가 있어도 해당 빌드는 성공할 수 있고, 작업 실패는 네트워크나 도구 체인 문제로 발생할 수도 있습니다. 경고 하나만 보고 디렉터리를 지우면 원인을 놓치거나 필요한 진단 자료를 없앨 수 있습니다.
실패 작업의 단계와 오류 로그를 먼저 확인한 다음, 같은 시간대의 호스트 여유 공간 및 사용량 기록과 대조하세요. 예를 들어 산출물 저장 단계에서 쓰기 오류가 난 기록과 당시 디스크 사용량이 함께 확인되면 용량 문제가 원인일 가능성이 높아집니다. 반대로 저장 공간이 충분하고 실패가 의존성 내려받기 단계에서 발생했다면 디스크 정리보다 네트워크와 도구 설정을 먼저 조사해야 합니다.
macOS의 저장 공간 항목을 확인할 때는 Apple의 저장 공간 설정 안내를 참고할 수 있습니다. 화면의 분류만으로 특정 빌드가 공간을 사용했다고 단정하지 말고, Jenkins 작업 기록과 실제 파일 점검 결과를 함께 보세요.
원인별로 점유 공간을 추적하세요
작업 공간이 남는 조건 확인
Jenkins 작업 공간은 작업이 끝났다고 항상 자동으로 비워지는 것이 아닙니다. Pipeline 설정과 정리 단계에 따라 이전 파일이 다음 빌드까지 남을 수 있으므로, 성공·실패·중단 작업의 종료 동작을 각각 점검하세요. Jenkins 문서는 Pipeline 작업 공간 동작을 설명하며, 별도의 정리 단계를 사용하는 방식은 Workspace Cleanup 단계 문서에서 확인할 수 있습니다.
특히 동시 실행이 설정된 작업은 실행별 작업 공간이 생기거나 파일이 겹치지 않도록 별도 경로를 사용하는 구성이 있을 수 있습니다. 실제 경로와 실행 기록을 확인하지 않은 채 작업 디렉터리를 한꺼번에 지우면, 진행 중인 빌드의 입력이나 실패 재현에 필요한 자료까지 사라질 수 있습니다. 팀의 Pipeline 정의는 Jenkins Pipeline 문법 문서와 대조해 종료 조건과 정리 단계가 의도대로 작성됐는지 검토하세요.
실패 작업의 작업 공간을 유지해야 하는지 먼저 정하세요. 진단에 필요한 로그와 입력 자료가 보존되지 않는다면 자동 정리보다 보존 위치와 만료 규칙을 마련하는 일이 우선입니다.
Xcode 구성 요소와 시뮬레이터를 구분
Xcode 본체, 플랫폼 지원 구성 요소, 추가 구성 요소, 시뮬레이터 런타임은 서로 다른 항목입니다. 프로젝트가 실제로 사용하는 Xcode 버전과 테스트 대상부터 확인하고, 사용하지 않는 구성 요소가 무엇인지 Xcode의 관리 화면에서 점검하세요. Apple은 Xcode 구성 요소를 내려받고 관리하는 방법을 안내합니다.
시뮬레이터 런타임도 해당 런타임을 선택하는 작업이나 테스트가 남아 있는지 확인한 다음 공식 관리 기능으로 정리해야 합니다. Xcode 프로젝트의 테스트 대상과 Apple의 추가 시뮬레이터 관리 안내를 함께 확인하세요. 시스템이 보호하는 디렉터리를 직접 찾아 삭제하는 방식은 일반적인 정리 절차로 삼지 마세요. 관리 기능 밖에서 제거하면 이후 Xcode가 기대하는 구성 요소 상태와 달라질 수 있습니다.
산출물과 진단 자료의 보존 기준 설정
아카이브, 디버그 기호 파일, 테스트 보고서, 로그, 임시 출력은 모두 같은 방식으로 다룰 수 없습니다. 다시 만들 수 있는 캐시와 배포·감사·장애 분석을 위해 남겨야 할 파일을 구분하고, 각각의 보존 위치와 정리 조건을 정하세요.
배포 검증에 필요한 자료를 지우기 전에 팀의 릴리스 절차와 보존 요건을 확인해야 합니다. Apple은 릴리스 빌드 테스트 안내에서 릴리스 빌드 검증을 다룹니다. 어떤 파일을 보존해야 하는지는 조직의 배포 및 감사 요건에 따라 달라지므로, 문서에 없는 보존 기간이나 공간 절감량을 정해진 값처럼 적용하지 마세요.
정리 전후에 안전성을 검증하세요
Jenkins의 Pipeline 문서에는 작업 종료 조건에 따라 후처리 단계를 작성하는 방법이 안내되어 있습니다. 정리 단계를 추가할 때는 작업 성공뿐 아니라 실패와 중단 상황에서도 의도한 동작을 하는지 확인하세요. Jenkins Pipeline 문서와 Workspace Cleanup 단계 문서를 기준으로 현재 설정을 대조할 수 있습니다.
아래 항목을 적용 전후에 확인하세요.
- [ ] 같은 시간대의 호스트 디스크 상태와 Jenkins 실패 작업의 로그를 나란히 확인했습니다.
- [ ] 작업 공간, Xcode 구성 요소, 시뮬레이터 런타임, 산출물과 로그를 서로 구분해 조사했습니다.
- [ ] 정리 대상이 진행 중인 작업의 파일이나 장애 진단 자료를 포함하지 않는지 확인했습니다.
- [ ] 삭제할 Xcode 구성 요소와 런타임을 프로젝트의 Xcode 버전 및 테스트 설정과 대조했습니다.
- [ ] 정리 단계를 적용한 뒤 의존성 확인, 시뮬레이터 선택, 실제 빌드와 테스트를 검증했습니다.
- [ ] 실패 작업을 재현하는 데 필요한 자료가 지정된 위치에 보존되는지 확인했습니다.
- [ ] 정리 작업이 예상과 다르게 동작할 때 설정을 되돌리는 절차를 마련했습니다.
정리 후 한 번의 빌드가 성공해도 정책이 안전하다고 단정하지 마세요. 실패 작업의 자료 보존과 정리 단계의 동작을 함께 확인해야 운영 환경에 적용할 수 있습니다.
반복 경고는 원인과 운영 부담을 함께 비교하세요
정리 뒤 디스크 경고가 다시 나타난다면, 최근 작업 기록에서 공간을 늘리는 작업 유형과 파일 종류를 찾아보세요. 반복적으로 재생성되는 작업 공간 문제라면 Pipeline의 정리 조건을 손볼 수 있습니다. 반면 배포용 아카이브나 진단 자료를 보존해야 해서 정리 폭을 넓힐 수 없다면, 필요한 보존 조건을 유지하면서 노드 운영 방식을 검토해야 합니다.
| 관찰 결과 | 먼저 확인할 대상 | 권장 판단 |
|---|---|---|
| 빌드가 끝난 뒤 작업 파일이 남아 있음 | Pipeline 후처리와 작업 공간 설정 | 정리 시점과 성공·실패별 보존 조건을 조정합니다 |
| 특정 Xcode 구성 요소가 더 이상 필요하지 않아 보임 | 프로젝트와 테스트가 참조하는 버전 | 공식 관리 기능에서 해당 구성 요소를 검토합니다 |
| 아카이브와 보고서가 계속 쌓임 | 배포·감사·장애 분석의 보존 요건 | 재생성 가능한 파일과 보존 대상의 위치 및 규칙을 분리합니다 |
| 정리해도 같은 작업에서 경고가 되풀이됨 | 대표 작업 기록, 동시 실행, 보존 조건 | 정리 정책으로 해결 가능한지 판단한 뒤 맥 CI 노드 조정을 검토합니다 |
원격 맥을 임시 빌드 환경이나 추가 노드 후보로 검토한다면, MACGPU의 원격 맥 이용 안내에서 실제 제공 조건을 확인하세요. 이미 자체 노드를 운영 중인 팀도 MACGPU 서비스 안내를 참고해 필요한 작업 기간과 운영 제약을 대조할 수 있습니다. 직접 구매한 맥은 장기간 일정한 부하와 물리적 연결 요구가 있을 때 적합할 수 있지만, 초기 구매와 유지 관리 책임이 따릅니다. 현재 환경에서 노드를 잠시 보완하거나 별도 빌드 환경을 검증해야 한다면 MACGPU의 원격 맥 대여를 후보로 비교하되, 확인되지 않은 용량이나 비용 절감 효과를 전제로 결정하지 마세요.
자주 묻는 질문
FAQ는 위에서 작업 공간, 런타임, 보존 자료를 다룬 내용을 바탕으로 정리했습니다. 실제 정리 범위는 팀의 작업 기록과 Xcode 설정으로 확인해야 합니다.
Jenkins Mac Agent에서 먼저 확인할 디렉터리는 어디인가요?
전체 저장 공간과 큰 항목을 확인한 뒤 Jenkins 작업 공간, Xcode 구성 요소 및 시뮬레이터 런타임, 빌드 산출물과 로그를 나눠 점검하세요. 실패 작업의 단계와 로그 시각을 디스크 기록에 맞춰야 원인이 용량인지 네트워크나 도구 오류인지 구분할 수 있습니다.
사용하지 않는 Xcode Simulator runtime을 안전하게 지울 수 있나요?
프로젝트와 테스트가 해당 런타임을 더 이상 사용하지 않는지 확인한 뒤 Xcode의 구성 요소 관리 기능으로 검토하세요. 정리 후에는 CI가 선택하는 시뮬레이터를 확인하고 실제 테스트 빌드를 실행해야 합니다. 보호된 디렉터리를 직접 삭제하는 방법을 일반 절차로 사용하지 마세요.
Jenkins 작업 공간을 정리하면 보존해야 할 파일도 삭제되나요?
정리 조건이 넓으면 실패 재현에 필요한 입력이나 테스트 결과까지 없어질 수 있습니다. 작업 성공·실패·중단 상황별 정리 범위를 확인하고, 필요한 로그와 산출물은 별도 위치에 보존하세요. 자동 정리를 적용하기 전에 실패 작업의 진단 자료가 남는지 검증하는 것이 중요합니다.
정리 후에도 맥 CI 디스크가 다시 부족해지면 노드를 조정해야 하나요?
대표 작업의 공간 증가 원인과 정리 주기, 동시 실행의 영향을 먼저 비교하세요. 필요한 릴리스 산출물과 장애 자료를 보존하면서 빌드를 이어가기 어려운 경우에는 노드 운영 방식 조정을 검토할 수 있습니다. 실제 기록 없이 고정된 용량 기준이나 확장 효과를 가정하지 말고 변경 후 같은 작업으로 검증하세요.