GitHub Actions ubuntu-latest 26.04 변경｜빌드 중단 전 YAML 점검
GitHub Actions의 ubuntu-latest가 Ubuntu 24.04에서 Ubuntu 26.04로 변경됩니다. GitHub는 Ubuntu 26.04 기반 x64·arm64 러너를 정식 지원하며, ubuntu-latest 전환은 2026년 10월 19일부터 11월 19일까지 순차적으로 진행합니다.
현재 워크플로가 정상이어도 운영체제 이미지에 사전 설치된 Node.js·Python·Java·Docker·Helm·데이터베이스 버전이나 패키지 구성이 달라지면 빌드가 실패할 수 있습니다. 전환 전에는 ubuntu-24.04로 실행 환경을 고정하고, 별도의 ubuntu-26.04 테스트 작업을 추가해 호환성을 확인하는 방법이 가장 안전합니다.
핵심 요약
- Ubuntu 26.04 러너는 x64와 arm64에서 정식 지원됩니다.
ubuntu-latest전환 기간은 2026년 10월 19일~11월 19일입니다.- 전환 기간에는 저장소와 실행 시점에 따라 24.04 또는 26.04가 배정될 수 있으므로 환경 재현성이 낮아질 수 있습니다.
- 준비되지 않은 저장소는
runs-on: ubuntu-24.04로 고정합니다. - Node.js·Python·Java 등 애플리케이션 런타임도 setup 액션으로 명시해야 합니다.
- 최종 전환 전 24.04와 26.04를 matrix로 병렬 검사하고 로그와 빌드 결과물을 비교합니다.
정보 기준일: 2026년 9월 18일. 러너 이미지에 포함되는 도구 버전은 이미지 업데이트에 따라 다시 바뀔 수 있으므로 실제 전환 전 GitHub runner-images 목록을 재확인해야 합니다.
목차
Ubuntu 26.04 정식 지원과 전환 일정
GitHub는 2026년 9월 17일 Ubuntu 26.04 러너 이미지의 공개 미리보기 단계를 종료하고 프로덕션 워크플로에서 사용할 수 있는 정식 지원 상태로 전환했습니다.
| 구분 | 내용 | 실무 조치 |
|---|---|---|
| Ubuntu 26.04 정식 지원 | 2026년 9월 17일 발표 | ubuntu-26.04로 사전 테스트 가능 |
| 지원 아키텍처 | x64·arm64 | arm64는 ubuntu-26.04-arm 레이블 사용 |
ubuntu-latest 전환 시작 |
2026년 10월 19일 | 시작일 전에 호환성 검사 완료 |
| 순차 전환 종료 예정 | 2026년 11월 19일 | 그 전까지 명시적 OS 레이블 권장 |
여기서 중요한 점은 10월 19일에 모든 워크플로가 한꺼번에 바뀌는 것이 아니라는 사실입니다. GitHub가 약 한 달 동안 점진적으로 레이블을 변경하므로 전환 기간에는 같은 ubuntu-latest 설정을 사용하는 워크플로라도 실행 시점에 따라 다른 운영체제 이미지에서 실행될 가능성이 있습니다.
ubuntu-latest를 그대로 쓰면 생기는 변화
ubuntu-latest는 특정 Ubuntu 버전을 영구적으로 의미하는 이름이 아닙니다. GitHub가 기본으로 지정한 최신 지원 이미지에 연결되는 이동형 레이블입니다.
jobs:
build:
runs-on: ubuntu-latest위 설정은 간단하지만 GitHub가 레이블의 대상 이미지를 바꾸면 저장소의 YAML을 수정하지 않아도 실행 환경이 달라집니다. 다음과 같은 워크플로는 특히 영향을 받을 수 있습니다.
- 시스템 기본
node,python,java명령의 버전에 의존하는 빌드 - 사전 설치됐다고 가정한 CLI·패키지·라이브러리를 바로 호출하는 작업
- Ubuntu 24.04의 apt 패키지명이나 저장소 구성에 맞춘 설치 스크립트
- Java 8, Miniconda, 특정 PHP·Docker·Helm 버전을 전제로 만든 작업
- OpenSSL·glibc·컴파일러 ABI 변화에 민감한 네이티브 모듈
- 브라우저나 데이터베이스의 기본 버전에 의존하는 통합 테스트
주의: GitHub Actions에서 운영체제 레이블을 고정해도 이미지 안의 모든 패키지 패치 버전까지 영구 고정되는 것은 아닙니다. 완전한 재현성이 필요한 도구는 setup 액션, 패키지 잠금 파일 또는 컨테이너 이미지 태그·다이제스트로 별도 고정해야 합니다.
Ubuntu 24.04와 26.04 주요 도구 차이
다음 표는 2026년 9월 18일 확인한 GitHub runner-images 소프트웨어 목록을 기준으로 정리한 대표적인 차이입니다. 전체 변경 목록이 아니며 이미지가 업데이트되면 세부 버전도 달라질 수 있습니다.
| 항목 | Ubuntu 24.04 이미지 | Ubuntu 26.04 이미지 | 예상 영향 |
|---|---|---|---|
| 기본 Node.js | 22.23.2 | 24.20.0 | 네이티브 모듈·엔진 조건 점검 |
| 기본 Python | 3.12.3 | 3.14.4 | 미지원 패키지·C 확장 빌드 점검 |
| 기본 Java | Java 17 | Java 25 | Gradle·Maven 플러그인 호환성 확인 |
| Java 8 | 사전 설치 목록에 포함 | 사전 설치 목록에서 제외 | 구형 프로젝트는 setup-java 필요 |
| Miniconda | 설치 및 CONDA 경로 제공 |
기본 목록에서 제외 | Conda 환경 생성 단계 실패 가능 |
| Helm | 3.21.4 | 4.2.4 | 차트·플러그인 호환성 점검 |
| Docker Engine | 28.0.4 | 29.4.2 | 빌드 옵션·Compose 동작 점검 |
| Docker Compose | 2.38.2 | 5.1.3 | 명령 옵션·파일 호환성 검사 |
| OpenSSL | 3.0 계열 | 3.5 계열 | 암호화 라이브러리·네이티브 바이너리 점검 |
| PostgreSQL | 16 계열 | 18 계열 | 확장·SQL·클라이언트 호환성 확인 |
| MySQL | 8.0 계열 | 8.4 계열 | 인증·SQL 모드·드라이버 검사 |
가장 위험한 부분은 “설치된 버전이 올라간다”는 사실보다 워크플로가 그 기본값을 암묵적으로 사용하고 있다는 점입니다. 예를 들어 python --version을 확인하지 않고 바로 패키지를 설치하면 Python 3.12에서는 성공하던 의존성이 Python 3.14에서 실패할 수 있습니다.
YAML에서 Ubuntu 버전 고정하기
아직 Ubuntu 26.04 호환성 검사를 완료하지 않았다면 기존 워크플로의 ubuntu-latest를 ubuntu-24.04로 변경합니다.
변경 전
name: Build
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm testUbuntu 24.04로 임시 고정
name: Build
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test이 조치는 자동 전환으로 인한 갑작스러운 장애를 피하기 위한 임시 안전장치입니다. Ubuntu 24.04에 계속 머무르는 것만으로 작업을 끝내기보다 별도의 테스트 작업에서 26.04 호환성을 검증해야 합니다.
검증 완료 후 Ubuntu 26.04로 명시적 전환
jobs:
build:
runs-on: ubuntu-26.04
steps:
- uses: actions/checkout@v4
- run: npm ci
- run: npm test24.04·26.04 병렬 테스트 방법
전환 전에 두 환경에서 동일한 설치·빌드·테스트 작업을 실행하면 운영체제 변경 때문에 발생하는 오류를 미리 찾을 수 있습니다.
name: Ubuntu compatibility test
on:
pull_request:
workflow_dispatch:
jobs:
test:
strategy:
fail-fast: false
matrix:
os:
- ubuntu-24.04
- ubuntu-26.04
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Show runner information
run: |
echo "Image OS: $ImageOS"
echo "Image version: $ImageVersion"
cat /etc/os-release
uname -a
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test
- name: Build
run: npm run build
fail-fast: false를 지정하면 한 환경이 실패해도 다른 환경의 작업이 중단되지 않습니다. 두 실행 결과를 모두 남길 수 있어 오류가 운영체제 변경 때문인지 프로젝트 자체 문제인지 비교하기 쉽습니다.
AI 에이전트의 코드 실행환경과 권한 구조도 함께 점검하려면 다음 글을 참고할 수 있습니다.
Agents API 실행환경 구성 확인하기Node.js·Python·Java 버전까지 고정하기
운영체제 레이블만 고정하고 시스템 기본 런타임을 그대로 사용하면 이미지 업데이트에 따라 다시 장애가 발생할 수 있습니다. 프로젝트가 요구하는 런타임은 공식 setup 액션으로 명시합니다.
Node.js 고정
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: '22'
cache: npm
- run: node --version
- run: npm ciPython 고정
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: pip
- run: python --version
- run: pip install -r requirements.txtJava 고정
- name: Set up Java
uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '17'
cache: gradle
- run: java -version
- run: ./gradlew test
package-lock.json, requirements.txt, Poetry·Pipenv 잠금 파일, Gradle Wrapper처럼 프로젝트 의존성을 고정하는 파일도 함께 관리해야 합니다. setup 액션의 런타임 버전과 애플리케이션 의존성 버전은 서로 다른 고정 계층입니다.
사전 설치 패키지 의존성 점검
워크플로에서 명령을 바로 호출하기 전에 필요한 도구가 실제로 존재하는지 확인합니다.
- name: Check required tools
shell: bash
run: |
set -euo pipefail
required_commands=(
node
npm
python
java
docker
jq
)
for command_name in "${required_commands[@]}"; do
if ! command -v "$command_name" >/dev/null 2>&1; then
echo "::error::$command_name is not installed"
exit 1
fi
done
node --version
npm --version
python --version
java -version
docker --version
jq --version필수 apt 패키지는 이미지에 들어 있을 것이라고 가정하지 말고 워크플로에서 직접 설치하는 편이 안전합니다.
- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y \
libssl-dev \
libsqlite3-dev \
pkg-config다만 Ubuntu 버전이 바뀌면 apt 저장소의 패키지명이나 제공 버전도 달라질 수 있습니다. 특정 패치 버전이 반드시 필요하다면 해당 버전이 26.04 저장소에도 존재하는지 먼저 확인하고, 필요하면 검증된 컨테이너 이미지를 사용하는 방안을 고려해야 합니다.
Conda를 사용하는 워크플로
Ubuntu 24.04 이미지에는 Miniconda와 CONDA 경로가 제공되지만 Ubuntu 26.04 목록에서는 기본 Miniconda가 빠졌습니다. 다음처럼 환경 변수의 존재를 가정한 작업은 실패할 수 있습니다.
# 피해야 할 예
- run: $CONDA/bin/conda env create -f environment.yml
Conda가 필요하다면 별도의 setup 액션이나 명시적인 설치 절차를 사용하고, 설치 후 conda --version과 환경 생성 결과를 검사해야 합니다.
Ubuntu 26.04 빌드 실패 원인 확인 방법
26.04 테스트가 실패하면 먼저 실행 환경과 도구 버전을 로그로 남깁니다. GitHub 호스팅 러너에서는 ImageOS와 ImageVersion 환경 변수를 확인할 수 있습니다.
- name: Collect environment diagnostics
if: always()
shell: bash
run: |
echo "ImageOS=$ImageOS"
echo "ImageVersion=$ImageVersion"
cat /etc/os-release
uname -a
command -v node && node --version || true
command -v npm && npm --version || true
command -v python && python --version || true
command -v java && java -version || true
command -v docker && docker version || true
command -v openssl && openssl version || true
dpkg-query -W -f='${Package} ${Version}\n' | sort > installed-packages.txt진단 파일은 실패한 실행에서도 내려받을 수 있도록 artifact로 보관할 수 있습니다.
- name: Upload diagnostic file
if: always()
uses: actions/upload-artifact@v4
with:
name: runner-diagnostics-${{ matrix.os }}
path: installed-packages.txt오류 유형별 우선 확인 항목
| 오류 증상 | 가능성이 큰 원인 | 우선 조치 |
|---|---|---|
command not found |
사전 설치 도구 제외 또는 PATH 변경 | 도구를 명시적으로 설치하고 PATH 확인 |
| npm·pip 의존성 설치 실패 | 기본 런타임 변화 또는 네이티브 모듈 미지원 | setup 액션으로 기존 런타임 고정 |
| 컴파일·링크 오류 | GCC·Clang·OpenSSL·시스템 라이브러리 변화 | 컴파일러와 개발 패키지 버전 비교 |
| Docker 빌드 차이 | Docker Engine·Compose 버전 변화 | 사용 옵션과 Compose 파일 검증 |
| DB 통합 테스트 실패 | 기본 PostgreSQL·MySQL 버전 변화 | service container에 DB 버전 명시 |
외부 업무 서비스와 MCP를 연결하는 자동화라면 실행환경뿐 아니라 관리자 허용과 접근 권한도 함께 확인해야 합니다.
Google Workspace Gemini MCP 확인하기권장 마이그레이션 순서와 롤백
- 워크플로 검색: 저장소의
.github/workflows에서ubuntu-latest사용 위치를 모두 찾습니다. - 현재 환경 기록: 정상 실행 중인 24.04 작업의 ImageVersion과 주요 도구 버전을 저장합니다.
- 운영 작업 고정: 배포·릴리스 작업은 우선
ubuntu-24.04로 고정합니다. - 26.04 병렬 검사: matrix에
ubuntu-26.04를 추가해 설치·테스트·빌드를 실행합니다. - 암묵적 의존성 제거: 런타임은 setup 액션, 시스템 패키지는 설치 단계, DB는 service container로 명시합니다.
- 결과물 비교: 테스트 성공 여부뿐 아니라 바이너리·정적 파일·컨테이너 이미지 생성 결과도 확인합니다.
- 26.04 명시 전환: 검증된 작업부터
runs-on: ubuntu-26.04로 바꿉니다. - 전환 후 관찰: 캐시 적중률, 빌드 시간, 테스트 실패, 배포 결과를 점검합니다.
장애 발생 시 즉시 롤백
jobs:
deploy:
# Ubuntu 26.04 장애 분석이 끝날 때까지 임시 롤백
runs-on: ubuntu-24.04롤백 후에는 단순히 “26.04에서 실패했다”라고 기록하기보다 실패 단계, ImageVersion, 사용한 런타임과 패키지 버전, 오류 메시지를 남겨야 합니다. 수정이 완료되면 pull request에서 26.04 검사를 다시 실행한 뒤 운영 작업을 재전환합니다.
배포 워크플로 주의: 운영 배포 작업을 처음부터 24.04·26.04 matrix로 동시에 실행하면 동일한 배포가 두 번 수행될 수 있습니다. 병렬 검사는 테스트·빌드 작업에 적용하고, 실제 배포 작업은 검증된 하나의 환경에서만 실행하십시오.
자주 묻는 질문
ubuntu-latest를 지금 바로 26.04로 바꿔야 하나요?
무조건 즉시 바꿀 필요는 없습니다. 현재 운영 중인 작업은 ubuntu-24.04로 고정하고, 테스트 작업에서 ubuntu-26.04 호환성을 먼저 확인하는 순서가 안전합니다.
ubuntu-24.04로 고정하면 모든 도구 버전도 고정되나요?
아닙니다. 운영체제 이미지 계열은 고정되지만 GitHub가 보안 패치와 도구 업데이트를 반영하면서 이미지 내부 버전은 달라질 수 있습니다. 중요한 런타임과 도구는 별도로 버전을 명시해야 합니다.
전환 기간에는 24.04와 26.04 중 어떤 이미지가 실행되나요?
GitHub는 2026년 10월 19일부터 11월 19일까지 순차적으로 레이블을 변경합니다. ubuntu-latest를 계속 사용하면 전환 기간 중 실행 환경을 저장소 YAML만으로 확정하기 어렵습니다. 정확한 환경이 필요하면 명시적 레이블을 사용하십시오.
arm64 워크플로는 어떤 레이블을 사용하나요?
GitHub 공식 발표에 따르면 Ubuntu 26.04 arm64 러너에는 ubuntu-26.04-arm 레이블을 사용합니다. 저장소와 요금제에서 해당 러너를 사용할 수 있는지도 함께 확인해야 합니다.
Ubuntu 26.04에서 Python 패키지 설치가 실패하면 어떻게 하나요?
먼저 python --version을 확인합니다. 시스템 기본 Python이 3.14 계열로 변경됐기 때문에 패키지가 아직 지원하지 않을 수 있습니다. actions/setup-python으로 기존에 사용하던 Python 3.12 등을 지정한 뒤 다시 테스트하십시오.
Miniconda를 사용하던 작업은 무엇을 확인해야 하나요?
Ubuntu 26.04 이미지에서는 Ubuntu 24.04에 있던 기본 Miniconda와 CONDA 경로를 그대로 가정하면 안 됩니다. 별도의 설치 또는 setup 액션을 추가하고 환경 생성이 정상적으로 끝나는지 확인해야 합니다.
정리
GitHub Actions Ubuntu 26.04 러너는 정식 지원됐으며, ubuntu-latest는 2026년 10월 19일부터 11월 19일까지 Ubuntu 24.04에서 26.04로 순차 전환됩니다.
가장 안전한 대응은 현재 운영 워크플로를 ubuntu-24.04로 임시 고정한 다음, ubuntu-26.04 병렬 테스트를 추가하는 것입니다. 이후 Node.js·Python·Java와 필요한 시스템 패키지를 YAML에 명시하고 테스트·빌드·배포 결과를 검증한 저장소부터 26.04로 전환하십시오.
