Jenkins 맥 빌드 노드 검수: 2026년 출시 전 점검

Jenkins에 애플 실리콘 빌드 노드를 추가하고 운영 승인 기준을 정해야 하는 플랫폼 엔지니어링 책임자에게 적합합니다.
원격 맥의 권한과 복구 능력을 확인해야 하는 기업 정보 기술 책임자, iOS 빌드 대기 시간과 배포 창을 관리하는 개발 생산성 책임자에게도 유용합니다.

판정 상자
단일 테스트가 성공했거나 에이전트가 온라인으로 표시된 상태는 생산 승인이 아닙니다. 실제 저장소와 실제 배포 파이프라인으로 실패 영역별 증거를 확보하지 못했다면, 승인 대신 제한된 시험 운영으로 분류해야 합니다.

Jenkins 화면의 온라인 표시는 컨트롤러와 에이전트 사이의 연결이 살아 있다는 뜻에 가깝습니다. 운영 가능 여부는 더 넓은 기준으로 판정해야 합니다.

Jenkins 공식 문서는 컨트롤러, 노드, 에이전트와 실행기를 구분합니다. 에이전트는 컨트롤러가 요청한 작업을 실행하고, 실행기는 동시에 실행할 작업 슬롯입니다. 또한 컨트롤러의 내장 노드에서 빌드를 실행하지 않는 구성을 권장합니다. Jenkins 노드 관리 문서와 컨트롤러 격리 문서에서 이 구조와 보안 경계를 확인할 수 있습니다.

검수 기록은 다음 열을 가진 표로 고정하는 편이 좋습니다.

• 확인 대상
• 실행 동작
• 기대 결과
• 원본 로그 위치
• 실패 시 조치
• 담당자
• 재검수 조건

샘플 프로젝트가 아니라 팀의 실제 저장소, 실제 의존성, 실제 서명 흐름을 사용해야 합니다. 업무와 관계없는 예제 앱이 성공해도 운영 환경의 용량과 권한 문제를 증명하지 못합니다.

에이전트 연결 방식

먼저 Jenkins 컨트롤러와 맥 에이전트가 어떤 방식으로 연결되는지 기록합니다. SSH 방식이라면 연결 사용자, 허용된 경로, 키의 보관 위치와 교체 절차를 확인합니다. 인바운드 방식이라면 에이전트 프로세스의 자동 시작 방식과 재접속 조건을 확인합니다.

검수할 항목은 다음과 같습니다.

• [ ] 에이전트 연결 방식과 연결 사용자를 구성 내보내기 파일로 보관합니다.
• [ ] 일시적인 네트워크 단절 뒤 에이전트가 다시 연결되는지 확인합니다.
• [ ] 연결 실패 시 Jenkins 로그와 맥 시스템 로그를 함께 보관합니다.
• [ ] 에이전트 사용자가 Jenkins 홈 디렉터리와 무관한 권한으로 실행되는지 확인합니다.
• [ ] 컨트롤러의 내장 노드 실행기가 운영 작업을 받지 않도록 설정합니다.

Jenkins 공식 문서에서는 컨트롤러의 실행기를 0으로 설정해 컨트롤러가 작업 실행보다 관리와 조정에 집중하도록 하는 방식을 설명합니다. 이 설정은 특정 Jenkins 버전이나 맥 성능을 보장하는 수치가 아니라, 컨트롤러와 빌드 노드의 역할을 분리하는 운영 기준입니다. Jenkins 에이전트 사용 문서에서 확인할 수 있습니다.

라벨과 파이프라인 배치

애플 실리콘 노드에는 프로젝트에서 알아보기 쉬운 라벨을 지정합니다. 예를 들어 macos, apple-silicon, xcode-signing처럼 기능과 보안 요구를 나누어 표현할 수 있습니다.

파이프라인에서는 전체 작업을 한 노드에 무조건 고정하기보다, 단계별 요구 사항에 맞춰 라벨을 선택하는 편이 안전합니다.

pipeline {
    agent none

    stages {
        stage('테스트') {
            agent { label 'macos && apple-silicon' }
            steps {
                sh 'xcodebuild test ...'
            }
        }

        stage('서명 및 보관') {
            agent { label 'macos && xcode-signing' }
            steps {
                sh 'xcodebuild archive ...'
            }
        }
    }
}

Jenkins 파이프라인은 agent의 라벨 조건에 따라 작업을 실행할 노드를 선택할 수 있습니다. 따라서 라벨을 설정한 뒤에는 반드시 파이프라인 로그에서 실제 노드 이름과 실제 도구 경로를 확인해야 합니다. 파이프라인 문법 공식 문서는 라벨 조건과 단계별 에이전트 사용 방법을 설명합니다.

자원 감시

Jenkins는 노드의 디스크 공간, 임시 공간, 스왑, 시계 동기화와 응답 시간을 감시할 수 있습니다. 이 항목을 단순한 상태 표시로 넘기지 말고, 운영 문턱으로 기록해야 합니다.

예를 들어 다음 상황은 연결 성공과 별개로 승인 보류 사유가 됩니다.

• 임시 디렉터리가 부족해 테스트 중간에 실패합니다.
• 시계가 맞지 않아 인증서나 저장소 접근이 불안정합니다.
• 캐시 정리 뒤 빌드 시간이 크게 흔들립니다.
• 피크 시간에 에이전트 응답은 살아 있지만 작업 대기열이 계속 증가합니다.

Xcode 실행 검증

xcodebuild -version 같은 버전 조회는 설치 여부만 보여줍니다. 운영 검수에서는 실제 프로젝트의 작업 공간 또는 프로젝트 파일을 열고, 의존성 복원부터 테스트와 아카이브까지 실행해야 합니다.

애플은 Xcode에 xcodebuild, simctl, devicectl 같은 명령줄 도구가 포함되며, Xcode를 활성 개발자 경로로 지정해야 해당 도구를 사용할 수 있다고 설명합니다. Xcode 명령줄 도구 문서에서 확인할 수 있습니다.

다음 세 가지 결과를 따로 보관합니다.

1. 깨끗한 작업 공간에서 실행한 결과
2. 캐시가 남아 있는 상태에서 실행한 결과
3. 파생 데이터와 의존성 캐시를 정리한 뒤 실행한 결과

세 결과가 모두 성공해야 한다는 뜻은 아닙니다. 중요한 것은 차이를 설명할 수 있어야 한다는 점입니다. 캐시가 없을 때만 실패한다면 용량과 네트워크, 의존성 잠금 상태를 별도 장애 영역으로 분류해야 합니다.

스위프트 패키지와 저장소 접근

스위프트 패키지를 사용하는 프로젝트라면 Package.resolved가 저장소에 포함되어 있는지 확인합니다. 애플은 지속적 통합 환경에서 예상한 의존성 버전을 유지하려면 이 파일을 저장소에 커밋해야 한다고 안내합니다. 또한 xcodebuild가 사용하는 맥 계정의 known_hosts와 SSH 설정도 검수 대상입니다. 스위프트 패키지 지속적 통합 공식 문서에서 세부 조건을 확인할 수 있습니다.

• [ ] Package.resolved가 실제 저장소에 존재합니다.
• [ ] 사내 저장소 접근에 필요한 SSH 키가 작업 계정에만 노출됩니다.
• [ ] 외부 저장소의 호스트 키 검증 실패를 임의로 무시하지 않습니다.
• [ ] 명령줄 도구와 Xcode 경로가 팀의 승인된 설정과 일치합니다.
• [ ] 도구 체인 변경 승인자와 되돌리기 방법이 문서화되어 있습니다.
• [ ] 새 Xcode 환경과 이전 환경을 병행할 라벨 또는 별도 노드가 있습니다.

주의
버전 조회 명령만 통과한 결과는 도구 체인 검수 증거로 부족합니다. 프로젝트 파일, 패키지 잠금 파일, 빌드 스크립트와 서명 단계를 실제로 실행한 로그가 있어야 합니다.

iOS 배포에서 가장 위험한 실패는 빌드가 실패하는 것이 아니라, 일반 테스트 작업이 배포용 비밀 정보에 접근하는 것입니다.

Jenkins 공식 문서는 자격 증명을 가능한 낮은 범위에 지정하고, 컨트롤러 전체에 등록된 자격 증명은 해당 컨트롤러의 여러 파이프라인에서 사용될 수 있다고 설명합니다. 프로젝트나 폴더별 범위가 필요한 경우 전역 등록을 피해야 합니다. Jenkins 자격 증명 보안 문서를 기준으로 권한을 설계합니다.

검수는 설정 화면만 보는 방식으로 끝내지 않습니다.

• [ ] 저장소 읽기 자격 증명과 배포 자격 증명을 분리합니다.
• [ ] 테스트 프로젝트가 배포용 자격 증명 식별자를 호출하지 못하는지 확인합니다.
• [ ] Jenkins 폴더와 프로젝트 단위로 자격 증명 범위를 제한합니다.
• [ ] 키체인 잠금과 해제 절차를 별도 단계로 기록합니다.
• [ ] 빌드 로그에 인증서 비밀 값과 토큰이 노출되지 않습니다.
• [ ] 낮은 권한의 테스트 작업으로 다른 프로젝트의 파일과 환경 변수를 조회해 봅니다.
• [ ] 개발 빌드 노드와 생산 서명 노드를 분리할 필요성을 검토합니다.

애플은 배포 인증서와 관련 계정 정보가 민감한 자산이며, 조직 밖으로 인증서를 공유하지 말아야 한다고 안내합니다. 인증서가 만료되거나 폐기되면 새 빌드나 업로드가 실패할 수 있으므로, 만료 감시와 교체 담당자도 검수 문서에 포함해야 합니다. 애플 인증서 개요에서 확인할 수 있습니다.

생산 서명 작업은 일반 테스트와 같은 작업 공간을 공유하지 않는 구성이 좋습니다. 물리적으로 분리할 수 없고 키체인이나 배포 자격 증명이 섞일 가능성이 있다면 해당 맥은 일반 테스트 노드로만 제한하는 편이 낫습니다.

한 대의 맥 에이전트를 여러 iOS 파이프라인이 공유할 수는 있습니다. 그러나 공유 가능성은 칩 이름이 아니라 실제 부하에서 판단해야 합니다.

Jenkins 공식 문서는 실행기 수를 노드의 자원과 작업 요구량으로 정해야 하며, 노드 하나에 실행기 하나를 가장 안전한 설정으로 설명합니다. 여러 실행기를 사용하려면 CPU, 메모리, 입출력과 네트워크 처리량을 관찰해야 합니다. Jenkins 노드 관리 문서에 기준이 정리되어 있습니다.

검수 순서는 다음과 같이 잡습니다.

• [ ] 실행기 하나로 기준 빌드 결과와 자원 사용량을 기록합니다.
• [ ] 팀의 실제 피크 대기열을 시간 순서대로 재현합니다.
• [ ] 실행기를 늘릴 때 CPU, 메모리, 디스크 입출력과 임시 공간을 함께 기록합니다.
• [ ] 서로 다른 브랜치가 같은 파생 데이터를 재사용하지 않는지 확인합니다.
• [ ] 시뮬레이터 상태와 키체인 상태가 다음 작업으로 넘어가지 않는지 확인합니다.
• [ ] 작업 종료 후 임시 파일과 생성물을 정리하는 절차를 실행합니다.
• [ ] 허용 가능한 대기 시간과 실패율을 넘으면 실행기 증가 대신 노드 추가를 검토합니다.

작업 공간을 공유해야 한다면 프로젝트별 경로를 분리하고, 서명 작업은 전용 라벨로 보내는 방식을 우선합니다. 실행기만 늘려 대기열을 줄이려 하면 디스크 입출력과 캐시 충돌이 먼저 발생할 수 있습니다. 따라서 실제 부하 기록 없이 특정 실행기 수를 정답처럼 지정해서는 안 됩니다.

원격 접속이 가능한 것과 무인 운영이 가능한 것은 다릅니다. SSH로 맥에 로그인할 수 있어도 파일볼트 잠금, 사용자 로그인, 키체인 잠금, 에이전트 자동 시작 중 하나가 막히면 야간 빌드는 멈출 수 있습니다.

애플은 맥의 원격 로그인을 켜면 SSH 또는 SFTP로 접근할 수 있으며, 원격 접근 사용자 범위를 제한할 수 있다고 설명합니다. 동시에 원격 로그인이 보안을 약화할 수 있으므로 허용 계정과 디스크 접근 범위를 신중히 설정해야 합니다. 애플 원격 로그인 문서에서 확인할 수 있습니다.

다음 테스트를 각각 실행하고, 복구에 필요한 권한과 수동 조작을 기록합니다.

• [ ] 계획된 맥 재시작 뒤 Jenkins 에이전트가 자동으로 시작됩니다.
• [ ] 에이전트 프로세스를 강제로 종료한 뒤 다시 연결됩니다.
• [ ] 짧은 네트워크 중단 뒤 연결과 작업 상태가 정상화됩니다.
• [ ] 디스크 공간 경고가 발생했을 때 새 작업이 차단되거나 담당자에게 알림이 갑니다.
• [ ] SSH 원격 로그인이 가능한 상태와 불가능한 상태를 구분합니다.
• [ ] 파일볼트 잠금 상태에서 필요한 복구 절차를 기록합니다.
• [ ] 키체인 잠금 때문에 서명 단계가 실패할 때 원인과 처리 방법을 확인합니다.
• [ ] 복구 뒤 실제 아카이브와 배포 전 검증까지 다시 실행합니다.

이 과정에서 복구 시간이 특정 값 이하라고 가정해서는 안 됩니다. 목표 시간은 팀의 야간 배포 창, 장애 대응 인력, 서비스 약속에 따라 정해야 하며, 실제 기록으로 검증해야 합니다.

검수 결과는 단순한 통과 또는 실패보다 다음 네 가지로 나누는 편이 운영에 유리합니다.

승인

연결, 배치, 도구, 서명, 동시 실행과 복구에 대한 원본 로그가 있고, 팀이 정한 문턱을 모두 충족한 상태입니다. 운영 담당자는 승인된 라벨과 허용된 파이프라인 범위를 기록합니다.

제한 시험 운영

기본 빌드는 가능하지만 피크 부하나 재시작 복구 증거가 부족한 상태입니다. 이 경우 배포 작업을 제한하고, 실제 업무 시간 외에 추가 부하 시험을 진행합니다.

수정 후 재검수

특정 장애 영역이 분명하고 수정 방법이 정해진 상태입니다. 예를 들어 자격 증명 범위가 너무 넓거나, 깨끗한 작업 공간에서 의존성 복원이 실패하는 경우가 해당합니다.

운영 거부

서명 비밀이 일반 작업에 노출되거나, 재시작 뒤 사람의 수동 조작 없이는 에이전트가 돌아오지 않거나, 허용 대기 시간을 지속해서 넘기는 상태입니다. 이 경우 노드 설정을 억지로 유지하지 말고 에이전트 분리, 독립 맥, 추가 용량을 검토해야 합니다.

최종 보고서에는 승인자, 재검수 날짜, 사용한 저장소 커밋, Jenkinsfile 버전, 노드 라벨, 실행 로그 위치와 실패 처리 담당자를 포함합니다. Jenkins 설정 내보내기만 저장하지 말고, 실제 파이프라인 로그와 맥의 도구 체인 정보도 함께 보관해야 합니다.

Jenkins 배포 구조를 처음 설계하는 경우에는 Jenkins iOS 지속적 통합 구성 안내를 먼저 확인하고, 원격 접근과 운영 계정 검토는 NUKCLOUD 도움말에서 제공 범위를 확인할 수 있습니다.

운영 전 검수의 핵심 기준

온라인 상태, 단일 빌드 성공, 실제 배포 가능 상태를 분리해야 합니다. 실제 저장소와 파이프라인으로 라벨 배치, Xcode, 의존성, 서명 자격 증명, 동시 실행과 복구를 모두 검증하지 않았다면 운영 승인을 보류해야 합니다.

iOS 작업을 특정 맥 노드에 고정하는 기준

애플 실리콘, 맥 운영 체제, Xcode와 서명 기능을 라벨로 나누고 파이프라인의 단계별 에이전트에 조건을 지정합니다. 단, 라벨이 맞아도 실제 로그의 노드 이름과 xcodebuild 경로가 일치하지 않으면 검수 실패로 처리해야 합니다.

한 에이전트의 여러 iOS 파이프라인 공유

공유는 가능하지만 작업 공간, 파생 데이터, 시뮬레이터, 키체인과 임시 디렉터리 오염을 재현 시험해야 합니다. 실행기 하나의 결과를 기준으로 삼은 뒤 실제 피크 대기열을 넣고, 대기 시간과 실패 변화에 따라 노드 수를 결정합니다.

원격 맥 재시작 뒤 에이전트 복구

에이전트 자동 시작, 네트워크 재접속, SSH 접근, 사용자 로그인, 키체인과 파일볼트 조건을 별도 검수해야 합니다. 사람이 화면을 열고 버튼을 눌러야 복구되는 구조라면 야간 무인 빌드용 노드로 승인하기 어렵습니다.

실행기 수 결정

Jenkins 공식 기준상 노드 하나에 실행기 하나가 가장 안전한 출발점입니다. 그 뒤 실제 작업으로 CPU, 메모리, 입출력, 임시 공간과 대기 시간을 측정합니다. 부하가 늘어날수록 실행기만 늘리기보다 맥 노드를 추가하는 방식을 비교해야 합니다.

검수용 맥을 사내 장비만으로 마련하면 장기간 고정 부하에는 유리할 수 있지만, 초기 구매 승인, 장비 배치, 교체 부품, 운영 계정, 원격 복구와 유휴 기간의 비용을 함께 부담해야 합니다. 기존 개발자의 맥을 공유하면 작업 중단과 권한 충돌이 생기고, 일반 클라우드 환경은 애플 실리콘과 실제 Xcode 서명 흐름을 원하는 방식으로 재현하기 어려울 수 있습니다.

반대로 검수 기간이나 출시 직전의 부하처럼 수요가 흔들리는 경우에는 원격 맥을 일정 기간 확보해 실제 Jenkins 파이프라인을 먼저 돌리는 방법이 합리적입니다. NUKCLOUD 요금 안내에서 제공 방식과 기간을 확인한 뒤, 연결 기록만이 아니라 동시 실행과 재시작 복구 증거까지 수집해야 합니다.

완료된 검수 결과를 기준으로 고정 노드와 탄력 확장 중 어느 쪽이 팀의 운영 조건에 맞는지 결정해야 합니다. 장기간 안정적인 고정 부하와 물리 장비 접근이 필수라면 직접 구매가 적합할 수 있습니다. 반대로 신규 노드의 생산 적합성을 먼저 확인하거나 피크 기간만 용량을 늘려야 한다면, 일정 기간 사용하는 원격 맥으로 시험 운영을 진행한 뒤 장기 자원 구성을 결정하는 편이 위험을 줄일 수 있습니다.