Jenkins Java 21 마이그레이션: 2026 Mac 노드는 어떻게 업그레이드할까

시작일에는 네 가지 실행 환경을 분리해 기록합니다

Jenkins Java 21 마이그레이션에서 가장 흔한 실패는 Java라는 이름이 붙은 항목을 하나의 설정으로 취급하는 것입니다. 실제로는 다음 네 가지를 따로 기록해야 합니다.

• Jenkins 컨트롤러 JVM
• Mac Agent JVM
• 프로젝트가 선택하는 JDK
• Xcode와 macOS 도구 체인

Jenkins 공식 정책에 따르면 LTS 2.555.1부터 컨트롤러 JVM과 Agent JVM은 Java 21 또는 Java 25를 사용해야 합니다. 이 버전 문턱은 Jenkins 공식 Java 지원 정책에서 확인해야 합니다.

반면 프로젝트가 요구하는 JDK는 Agent JVM과 별도로 선택할 수 있습니다. 따라서 오래된 Java 프로젝트를 빌드한다는 이유만으로 Mac Agent 자체를 이전 Java로 유지할 필요는 없습니다. 프로젝트의 컴파일러와 Jenkins 프로세스의 실행 JVM을 분리해야 합니다.

시작일에 다음 항목을 자산 목록으로 고정합니다.

• 컨트롤러의 Jenkins 버전과 JVM 버전
• 각 Mac Agent의 macOS 버전, Java 버전, JAVA_HOME
• Agent 실행 방식과 재부팅 뒤 시작 방식
• 노드 라벨과 작업 라우팅 규칙
• 핵심 플러그인, 인증 플러그인, 자격 증명 플러그인, Pipeline 플러그인
• Xcode 경로, 서명 키체인 접근 방식, 작업 디렉터리

Jenkins의 노드 관리 문서는 노드의 연결과 실행 환경을 확인하는 기준으로 사용할 수 있습니다. 노드가 현재 온라인이라는 사실만으로 Java 21 전환 가능성을 판단하면 안 됩니다.

업그레이드 창 전에는 기준선과 복구 대상을 고정합니다

컨트롤러를 변경하기 전에 목표 LTS의 업그레이드 안내와 변경 기록을 읽습니다. 특히 플러그인 하나가 로드되지 않는 문제와 Agent가 연결되지 않는 문제는 원인이 다르므로, 같은 복구 절차로 처리하지 않아야 합니다.

2.555 업그레이드 안내를 기준으로 다음 자료를 별도 보관합니다.

• 컨트롤러 설정 백업
• 현재 플러그인 버전 목록
• Mac Agent의 실행 명령과 시작 인자
• JAVA_HOME과 PATH 같은 환경 변수
• 노드 라벨 및 작업 큐 라우팅 기록
• 최근 성공한 Xcode 빌드의 로그와 생성물

복구 대상도 세 갈래로 나눕니다.

첫째는 컨트롤러 Jenkins 버전입니다. 둘째는 Agent JVM과 실행 경로입니다. 셋째는 작업 라벨과 노드 라우팅입니다. 세 가지를 동시에 되돌리면 어느 변경이 장애를 만들었는지 알 수 없습니다.

Agent의 Java 버전 표시가 필요하다면 Jenkins의 Versions Node Monitors 플러그인 설명을 참고할 수 있습니다. 다만 플러그인이 보여 주는 정보는 운영 판단의 보조 자료로 사용하고, Mac에서 직접 실행한 버전 확인 결과도 함께 보관해야 합니다.

첫 번째 격리 Mac에서 Java 21을 적용합니다

생산 서명과 정식 배포를 맡지 않는 Mac Agent를 하나 선택합니다. 해당 노드에는 Java 21을 설치하고 Agent 프로세스의 실행 경로를 명시합니다. Jenkins의 Agent 실행 방식은 공식 Agent 사용 문서와 현재 조직의 시작 방식을 함께 대조해야 합니다.

Mac 셸에서 필요한 확인은 다음처럼 최소화할 수 있습니다.

echo "$JAVA_HOME"
"$JAVA_HOME/bin/java" -version

출력에는 해당 경로의 Java 21이 표시되어야 합니다.

openjdk version "21..."

위 명령의 버전 표시 자체는 Jenkins의 Java 지원 정책과 대조합니다. 조직에서 사용하는 Java 배포판과 정확한 패치 버전의 지원 여부는 별도로 확인해야 하며, 위 예시의 생략 부호를 특정 제품이나 버전으로 해석하면 안 됩니다.

Agent를 다시 연결한 뒤에는 다음 순서로 확인합니다.

1. Jenkins가 노드를 온라인 상태로 표시하는지 확인합니다.
2. 노드 정보에서 JVM 버전과 시스템 정보를 확인합니다.
3. 네트워크를 잠시 끊은 뒤 Agent가 다시 연결되는지 확인합니다.
4. Mac을 재시작한 뒤 Agent가 자동으로 복귀하는지 확인합니다.
5. 작업 라벨이 의도한 노드에만 적용되는지 확인합니다.

이때 프로젝트 JDK는 바꾸지 않습니다. Jenkins Tool, 환경 변수 또는 빌드 스크립트에서 프로젝트별 JDK를 선택하고, Agent 프로세스는 Java 21 경로를 계속 사용하게 해야 합니다.

예를 들어 Pipeline 안에서 확인할 때도 Agent JVM과 프로젝트 도구를 혼동하지 않도록 이름을 분리합니다.

sh 'echo "agent runtime: $JAVA_HOME"'
sh 'xcodebuild -version'

Xcode의 실제 버전과 명령 줄 도구 경로는 Apple Xcode 명령 줄 도구 참고 자료를 기준으로 기록합니다.

첫 번째 실제 Xcode 작업으로 경계를 검증합니다

Java 21로 Agent가 연결됐다는 사실만으로 iOS CI/CD가 안전하다고 판단할 수 없습니다. 대표 작업 하나를 선택해 소스 가져오기, 의존성 복원, Xcode 빌드, 테스트, 생성물 업로드까지 실행해야 합니다.

시험 단계에서는 생산 서명을 바로 사용하지 않는 편이 안전합니다. 비생산 자격 증명이나 읽기 전용 검증 작업으로 먼저 실행하고, 통과 뒤에만 서명과 배포 작업을 별도 노드에서 확인합니다. 키체인 접근과 코드 서명은 Apple의 서명된 코드 생성 안내를 기준으로 점검합니다.

실패 지점을 다음처럼 분류하면 원인 추적이 쉬워집니다.

• Agent 연결 또는 재연결 실패
• 플러그인 호출 실패
• 프로젝트 JDK 선택 실패
• Xcode 또는 의존성 복원 실패
• 키체인 권한과 서명 실패
• 생성물 업로드 실패

특히 Java 21 전환 직후 Xcode 빌드가 실패했다면 Java 문제라고 단정하지 않아야 합니다. 작업 디렉터리 권한, 키체인 잠금 상태, Xcode 선택 경로, 플러그인 호출 로그를 각각 확인해야 합니다.

컨트롤러 업그레이드 뒤에는 작업을 두 갈래로 전환합니다

격리 Mac Agent와 핵심 플러그인이 통과한 뒤에만 컨트롤러 업그레이드 창을 엽니다. 목표 LTS와 지원되는 JVM 조합은 Jenkins 공식 문서에서 다시 확인해야 합니다. 플러그인 호환성은 전체 플러그인에 일괄 적용된다고 가정하지 말고, 인증과 자격 증명, Pipeline처럼 실제 작업에 관여하는 항목부터 확인합니다.

업그레이드 직후에는 아직 이전 기준의 노드를 생산 라우팅에서 완전히 제거하지 않습니다. 다만 호환되지 않는 Agent로 작업이 잘못 배정되지 않도록 라벨과 큐 규칙을 분리합니다.

권장 전환 순서는 다음과 같습니다.

• 비배포 작업을 Java 21 Agent로 전환합니다.
• 연결 끊김과 재연결 로그를 확인합니다.
• 아카이브 작업을 전환합니다.
• 마지막에 서명과 배포 작업을 전환합니다.
• 각 단계에서 대표 Xcode 작업을 다시 실행합니다.

어느 단계에서든 Agent가 오프라인이 되면 다음 단계로 진행하지 않습니다. 컨트롤러 버전, Agent 실행 경로, 작업 라우팅 중 한 항목만 되돌리고 재시험해야 합니다.

첫 주에는 통과한 노드만 새로운 기준으로 등록합니다

한 번의 성공한 빌드는 운영 기준이 아닙니다. 첫 주에는 Agent 오프라인 발생, 재연결, 호스트 재시작 뒤 복귀, 플러그인 오류, Xcode 빌드 실패를 각각 기록합니다. 성능 향상이나 장애율 감소를 근거 없이 수치로 표현해서는 안 됩니다.

Java 21 전환을 통과한 노드에는 다음 기준을 고정합니다.

• Agent JVM의 Java 실행 경로
• 프로젝트별 JDK 선택 방법
• Xcode 경로와 명령 줄 도구 상태
• 키체인과 서명 작업의 실행 노드
• 노드 라벨과 허용 작업
• 재시작과 재연결 방법
• 장애 때 되돌릴 대상과 담당자

기존 기기에 격리 공간이 없거나 유일한 생산 Mac을 멈출 수 없다면, 원래 노드에서 바로 시험하지 않아야 합니다. 이때는 Mac 미니 원격 이용 환경을 별도 검증 노드로 검토할 수 있습니다. 서울 인근 작업자의 지연 조건을 따로 확인해야 한다면 서울 Mac 미니 이용 안내도 비교 대상에 넣을 수 있습니다.

전환 전 실행 확인 목록

• [ ] 컨트롤러 JVM과 모든 Mac Agent JVM을 목록화했습니다.
• [ ] 프로젝트 JDK와 Xcode 도구 체인을 별도 항목으로 기록했습니다.
• [ ] 목표 LTS와 핵심 플러그인의 지원 내용을 확인했습니다.
• [ ] 컨트롤러 설정과 Agent 실행 정보를 백업했습니다.
• [ ] 생산 서명을 맡지 않는 격리 Mac을 지정했습니다.
• [ ] Java 21 경로로 Agent 연결을 확인했습니다.
• [ ] 단절, 재연결, 호스트 재시작 뒤 복귀를 확인했습니다.
• [ ] 실제 Xcode 빌드와 테스트를 실행했습니다.
• [ ] 비배포 작업부터 단계적으로 전환할 라벨을 정했습니다.
• [ ] 컨트롤러, Agent JVM, 라우팅을 따로 되돌릴 계획을 작성했습니다.

FAQ

Jenkins 업그레이드 전에 Mac Agent부터 준비해야 하나요?

그렇습니다. 먼저 모든 Mac Agent의 Java 버전과 실행 경로, 재접속 방식, 노드 라벨을 조사해야 합니다. 격리된 노드에서 Java 21로 Agent 연결과 재시작 뒤 자동 복귀를 확인한 다음 컨트롤러를 올리는 순서가 안전합니다. 컨트롤러를 먼저 업그레이드하면 기존 Java로 실행되던 Agent가 동시에 오프라인이 될 수 있습니다.

Mac에서 Jenkins Agent가 Java 21을 사용하게 하려면 어떻게 하나요?

Mac의 Agent 프로세스가 사용하는 JAVA_HOME 또는 Java 실행 파일의 절대 경로를 명시합니다. 프로젝트 빌드 스크립트의 JDK 설정과 Agent 실행 경로를 같은 값으로 바꾸면 안 됩니다. 연결 뒤 Jenkins 노드 정보에서 실제 JVM 버전을 확인하고, 호스트 재시작과 네트워크 단절 뒤 재연결까지 함께 시험해야 합니다.

Jenkins Agent가 Java 21이어도 오래된 Java 프로젝트를 빌드할 수 있나요?

가능합니다. Jenkins 공식 문서는 Agent JVM과 프로젝트 빌드에 사용하는 JDK를 분리해 관리할 수 있다고 설명합니다. 프로젝트가 요구하는 오래된 JDK는 Jenkins Tool 설정이나 환경 변수, 빌드 스크립트에서 별도로 선택합니다. 다만 해당 프로젝트의 플러그인과 빌드 도구가 그 JDK를 지원하는지는 실제 파이프라인에서 확인해야 합니다.

Jenkins 업그레이드 뒤 Mac 노드가 오프라인이면 어떻게 되돌리나요?

먼저 작업 라우팅을 중지하고 해당 노드의 Agent JVM 경로와 시작 인자를 이전 값과 비교합니다. 컨트롤러 버전, Agent Java 실행 환경, 작업 라벨을 한꺼번에 되돌리지 말고 한 항목씩 복구해야 원인을 구분할 수 있습니다. 컨트롤러 설정 백업과 기존 Agent 실행 정보가 없다면 즉시 복구보다 격리 노드 재등록이 안전합니다.

여러 Mac Agent를 Java 21로 옮길 때 어떤 순서가 적절한가요?

먼저 생산 서명에 사용하지 않는 단일 Mac Agent를 선택합니다. 연결, 단절 뒤 재연결, 호스트 재시작 뒤 복귀, 대표적인 Xcode 빌드와 테스트를 통과시킨 뒤 비배포 작업부터 옮깁니다. 각 단계에서 실패 분류와 되돌리기 결과를 기록하고, 통과한 실행 경로와 환경을 다음 노드의 기준으로 사용해야 합니다.

현재 환경과 원격 Mac을 비교해 임시 용량을 결정합니다

유일한 사내 Mac을 계속 사용하는 방식은 별도 시험 공간이 없고, 재부팅이나 라우팅 변경을 생산 작업과 분리하기 어렵다는 단점이 있습니다. 또 장비를 추가 구매하면 검증 기간이 끝난 뒤에도 하드웨어 감가, 유지 보수, 보관과 교체 계획을 계속 부담해야 합니다.

반대로 원격 Mac을 임시로 추가하면 Java 21 시험 노드를 생산 Mac과 분리할 수 있습니다. 다만 장기적으로 계속 높은 부하를 처리하거나 물리 장치 연결이 필요한 팀에는 직접 구매가 더 적합할 수 있습니다. 단기 회귀 시험, 업그레이드 창, 예비 Agent가 필요한 경우에는 NodeMini의 Mac 이용 방식을 확인한 뒤 실제 Jenkins와 Xcode 조건을 검증하는 편이 합리적입니다.

먼저 위 목록에서 격리 시험, 이중 라우팅, 빠른 복구 항목을 확인해야 합니다. 세 조건 중 하나라도 부족하고 유일한 생산 Mac을 멈출 수 없다면, 단기 원격 Mac Agent를 추가해 Java 21과 실제 Xcode 작업을 검증한 뒤 장기 용량을 결정하는 순서가 안전합니다.