openssl 버전 확인이나 CI 작업이 갑자기 실패한다면, 기본값 변경이 원인인지 먼저 분리해야 합니다.

빠른 결론: OpenSSL 4 전환만으로 모든 macOS CI가 실패하지는 않습니다. 같은 Runner에서 버전별 파이프라인을 비교하고, 특정 명령 동작이나 OpenSSL 3에 의존하는 작업만 수정하거나 버전을 명시하세요.

이 글은 GitHub Actions macOS 워크플로를 관리하며 Runner 기본값 변경 전에 영향을 확인하려는 엔지니어를 위한 안내입니다.
OpenSSL을 사용하는 네이티브 의존성이나 Ruby·Python 런타임을 유지하는 개발자도 컴파일, 링크, 실행 단계별로 확인할 수 있습니다.
빌드 노드를 관리하는 DevOps 엔지니어는 OpenSSL 4 적용과 OpenSSL 3 고정 중 어느 쪽이 적절한지 판단할 수 있습니다.

마지막 업데이트: 2026년 10월 23일. 일정과 적용 범위는 Runner Images 공식 공지와 macOS 26 Runner 소프트웨어 목록을 기준으로 확인했습니다.

기본값 변경 범위와 적용 일정

공지된 변경은 macOS 26 및 Xcode 27 Runner에서 기본 openssl 명령이 3.x에서 4.x로 바뀌는 내용입니다. OpenSSL 3을 제거하는 변경은 아니며, 공지에 적힌 단계적 적용 기간은 2026년 11월 2일부터 11월 8일까지입니다. 따라서 2026년 10월 23일 현재 이를 이미 모든 Runner에 적용된 상태로 간주하면 안 됩니다. 실제 일정이나 범위는 공식 공지의 후속 업데이트를 확인하세요.

이 변경만으로 모든 작업의 실패를 예측할 수는 없습니다. 영향은 기본 명령의 버전을 전제로 하는 스크립트, 특정 API에 의존하는 프로그램, 실제로 로드되는 라이브러리의 조합에 따라 달라집니다. OpenSSL 공식 문서는 4.0을 주 버전 변경으로 설명하고, 사용 중단된 API에 의존하는 프로그램은 조정이 필요할 수 있다고 안내합니다. 프로젝트가 반드시 호환되지 않는다는 뜻은 아닙니다. (OpenSSL 4.0 마이그레이션 안내)

실제 openssl 경로와 스크립트 가정 확인

GitHub Actions macOS Runner에서 실행되는 명령이 예상과 다른 버전을 가리키는지 확인할 때는 버전 문자열만 보지 말고 경로와 환경 변수를 함께 기록하세요. 다음 명령을 CI 작업에 임시로 추가하면, 해당 작업이 어떤 실행 파일을 호출하는지 살펴볼 수 있습니다.

type -a openssl
command -v openssl
openssl version -a
printf '%s\n' "$PATH"

openssl version의 출력 형식이나 옵션을 파싱하는 스크립트도 점검 대상입니다. 버전 숫자가 바뀌었을 때 이를 빌드 실패로 처리하는 분기, PATH에서 특정 디렉터리를 가정하는 코드, 기본 옵션에 기대는 명령을 찾아보세요. 버전 확인 명령의 동작은 OpenSSL version 문서와 비교할 수 있습니다.

로그를 남길 때는 민감 정보가 출력되지 않도록 주의하세요. GitHub Actions 로그에 값을 전달하는 방법과 워크플로 명령은 GitHub Actions 공식 문서를 참고하세요. 명령 경로와 버전이 달라졌더라도 실제 작업이 성공한다면, 버전 문자열만을 기준으로 실패 처리하는 분기부터 수정하는 편이 안전합니다.

네이티브 의존성의 컴파일·링크·로드 분리

실패 로그에서 처음 나타난 오류가 어느 단계에 속하는지 구분하세요. 헤더 또는 API 오류는 컴파일 문제일 수 있고, 심볼을 찾지 못하는 메시지는 링크 단계의 문제일 수 있습니다. 실행 중 라이브러리를 찾지 못하거나 예상과 다른 파일을 읽는다면 로드 경로를 확인해야 합니다. 이 세 가지를 모두 “OpenSSL 버전 오류”로 묶으면 잘못된 해결책을 선택하기 쉽습니다.

프로그램이 OpenSSL 명령줄 도구를 호출하는지, OpenSSL 라이브러리에 직접 연결되는지도 따로 확인하세요. openssl version 결과는 명령이 선택한 실행 파일의 버전을 보여줄 뿐, 앱 프로세스가 실제로 어떤 라이브러리를 로드하는지 증명하지 않습니다. 실행 파일의 의존성을 확인하고, 실제 실행 환경의 라이브러리 경로를 검사하세요. macOS의 동적 라이브러리 로드 경로는 Apple의 런타임 라이브러리 안내에서 확인할 수 있습니다.

의존성의 지원 버전은 추측하지 마세요. 해당 라이브러리의 공식 호환성 문서를 확인한 뒤, 프로젝트가 사용하는 버전과 빌드 옵션으로 실제 Runner에서 빌드하고 테스트해야 합니다. Ruby나 Python 같은 런타임을 사용하는 경우에도 인터프리터가 호출하는 openssl 명령과 확장 모듈이 연결하는 라이브러리를 각각 살펴보세요.

TLS와 인증서 작업의 실제 동작 재검증

인증서 생성, 인증서 정보 확인, 키 처리, TLS 연결처럼 파이프라인이 실제로 수행하는 작업을 빠짐없이 재실행하세요. 명령이 성공했는지만 확인하지 말고 옵션, 종료 상태, 생성 파일의 형식과 후속 작업의 입력까지 확인해야 합니다. x509 명령의 옵션과 동작은 OpenSSL x509 문서에서 대조할 수 있습니다.

특히 OpenSSL CLI 테스트가 통과해도 애플리케이션의 TLS 작업까지 호환된다고 단정하지 마세요. 앱이 다른 라이브러리를 로드하거나 별도의 기본값을 사용할 수 있습니다. 파이프라인에 인증서 생성과 검증, 앱의 실제 TLS 연결이 있다면 각각의 성공 여부를 별도 로그로 남기세요.

로컬과 Runner의 환경 차이 분리

로컬에서는 통과하지만 Runner에서 실패할 때는 두 환경의 PATH, CPU 아키텍처, 이미지, 의존성 설치 방식과 실제 로드된 라이브러리를 비교하세요. 캐시가 남아 있거나 도구 체인이 달라진 경우에도 OpenSSL 변경으로 오인할 수 있습니다. GitHub Actions Runner 선택 안내에서 작업이 어떤 Runner를 대상으로 하는지 확인하고, 같은 커밋을 기준으로 로그를 나란히 비교하세요.

변경 전후를 비교할 때는 대표 작업을 고정해야 합니다. 최소한 의존성 설치와 컴파일, 단위 테스트, 인증서 또는 TLS 검증을 포함하세요. 각 작업에서 실행 파일 경로와 버전, 종료 상태를 기록하고, 실패가 처음 발생한 단계도 남기세요. 이렇게 해야 이미지 변화나 캐시 영향과 OpenSSL 호환성 문제를 분리할 수 있습니다.

  • [ ] Runner 이미지와 실제 작업 대상이 같은지 확인합니다.
  • [ ] openssl 실행 파일 경로와 버전을 로그에서 확인합니다.
  • [ ] 버전 문자열 또는 기본 옵션에 의존하는 스크립트를 찾습니다.
  • [ ] 네이티브 의존성의 컴파일, 링크, 실행 로그를 따로 검토합니다.
  • [ ] 인증서와 TLS 명령뿐 아니라 앱 자체의 TLS 작업도 실행합니다.
  • [ ] 변경 전후에 같은 커밋과 대표 작업을 사용합니다.
  • [ ] 실패 시 되돌릴 버전과 전환 중단 조건을 기록합니다.

결과에 따른 버전 선택

의존성과 테스트가 OpenSSL 4에서 정상 동작하면 새 기본값을 대상으로 수정 사항을 반영하고, 대표 파이프라인을 다시 검증하세요. 반대로 특정 의존성이 OpenSSL 3을 요구하거나 결과가 불안정하면 Runner 기본값을 추정하지 말고 OpenSSL 3을 명시적으로 선택하세요. 공식 Runner 공지도 기본값 변경과 별도로 OpenSSL 3이 유지된다고 설명합니다. 적용 전에 해당 Runner 이미지의 소프트웨어 목록에서 실제 설치 상태를 재확인하세요.

선택지 적합한 조건 확인할 항목 주의할 점
OpenSSL 4에 맞춰 전환 의존성 지원을 확인했고 대표 작업이 통과한 경우 스크립트 분기, API 사용, CLI 옵션, 앱 런타임 버전 문자열 검사만 통과 기준으로 삼지 않습니다
OpenSSL 3을 명시적으로 사용 의존성이 OpenSSL 3을 요구하거나 전환 검증이 끝나지 않은 경우 설치된 버전, 실행 경로, 실제 로드 라이브러리 Runner의 기본값이 계속 유지된다고 가정하지 않습니다
전환을 보류하고 추가 검증 실패 원인이 이미지나 캐시 변화와 구분되지 않는 경우 같은 커밋의 전후 로그, 캐시 상태, 되돌리기 조건 원인 확인 전 여러 설정을 동시에 바꾸지 않습니다

현재의 관리형 CI만으로 검증이 어려운 이유가 Runner 기본값 변화와 환경 차이를 재현하기 어렵다는 데 있다면, 독립된 실제 Mac 노드에서 같은 프로젝트의 파이프라인을 비교하는 방안도 검토할 수 있습니다. 다만 장기간 반복되는 고정 부하나 물리 인터페이스가 필요한 작업은 임시 원격 환경보다 자체 장비가 더 적합할 수 있습니다. 별도 Mac이 필요한 기간과 예산을 먼저 따져보고, 필요할 때 RUVCLOUD의 요금 안내와 원격 Mac 신청 정보를 확인해 독립 검증 노드가 현재 CI보다 적합한지 판단하세요.