Expo EAS OTA auth token failures: root causes, diagnostics, and release hardening

Expo EAS Update OTA 배포 실패는 한 원인으로 뭉뚱그리기보다 인증/권한 , channel → branch 라우팅 , runtimeVersion 호환성 , 코드 서명 , 환경변수/런타임 설정 , 클라이언트 적용·롤백 조건 으로 분리해 진단해야 한다. eas update가 성공적으로 publish되더라도 클라이언트가 해당 업데이트를 받는다는 뜻은 아니며, 빌드에 박힌 channel/runtimeVersion/platform/code-signing 조건

Summary#

Expo EAS Update OTA 배포 실패는 한 원인으로 뭉뚱그리기보다 인증/권한, channel → branch 라우팅, runtimeVersion 호환성, 코드 서명, 환경변수/런타임 설정, 클라이언트 적용·롤백 조건으로 분리해 진단해야 한다. eas update가 성공적으로 publish되더라도 클라이언트가 해당 업데이트를 받는다는 뜻은 아니며, 빌드에 박힌 channel/runtimeVersion/platform/code-signing 조건이 모두 맞아야 한다.

Key Points#

1. CI/CD 인증 토큰 실패 모드#

자동화 환경에서는 EXPO_TOKEN 같은 Expo access token을 CI secret으로 주입해 EAS CLI를 인증한다.
토큰이 없거나 잘못된 계정/조직 권한을 가리키면 eas update는 publish 단계에서 실패하거나 프로젝트/브랜치 접근이 거부된다.
GitHub Actions에서는 expo/expo-github-action 또는 직접 설치한 eas-cli 단계에 secret token을 명시적으로 전달한다.
하드닝: publish 전에 eas whoami 및 프로젝트 식별자 확인을 수행해 토큰·계정 오류를 early-fail로 만든다.

2. Channel → Branch → runtimeVersion 라우팅#

클라이언트가 OTA를 받으려면 다음 조건이 동시에 맞아야 한다.

조건	확인 지점	흔한 실수
channel이 의도한 branch에 연결됨	`eas channel:list`, `eas channel:view`, `eas channel:edit`	channel 생성 후 branch 연결 누락
update가 올바른 branch에 publish됨	`eas update --branch ...` 또는 workflow 설정	staging/prod branch 혼동
빌드의 runtimeVersion과 update runtimeVersion이 일치	app config / native build metadata	앱 버전·SDK·native 변경 후 runtimeVersion 미갱신
platform이 일치	iOS/Android update group	한 플랫폼만 publish되었는데 양쪽 배포로 오해

eas update 성공은 “서버에 update group이 생성됨”에 가깝고, “모든 설치 앱이 적용함”을 의미하지 않는다.

3. runtimeVersion 정책 갱신#

이전 초안의 fingerprintExperimental 권장은 stale하다. 현재 문서·관행에서는 실험적 명칭을 그대로 권장하기보다 Expo가 지원하는 최신 runtimeVersion 정책명과 프로젝트 SDK 기준을 확인해야 한다.
안전한 원칙은 “native runtime이 바뀌면 기존 OTA와 호환되지 않게 runtimeVersion을 분리한다”이다.
appVersion 정책은 앱 버전과 OTA 호환성을 단순하게 묶을 때 유용하지만, native dependency 변경이 앱 버전에 정확히 반영되지 않는 팀에서는 별도 검증이 필요하다.
fingerprint 계열 정책은 native/project fingerprint 기반 호환성 관리에 유용할 수 있으나, 사용 중인 Expo SDK와 EAS CLI 문서의 현재 명칭·안정성 표시를 확인한 뒤 적용한다.

4. 코드 서명 실패 모드#

코드 서명을 강제하도록 빌드된 바이너리는 서명되지 않았거나 잘못 서명된 update를 거부한다.
eas update --private-key-path 누락, 인증서/키 불일치, rotation 후 구버전 바이너리 호환성 착각이 주요 원인이다.
private key는 repo에 커밋하지 말고 CI secret/KMS/Secret Manager로 주입한다.
키 교체 후에는 어떤 바이너리가 어떤 certificate를 trust하는지 추적하고, 필요하면 새 runtimeVersion 또는 새 binary release로 분리한다.

5. 환경변수와 EAS Build / EAS Update 경계#

EAS Build의 native build-time env와 EAS Update의 JavaScript bundle 생성 시점 env를 구분해야 한다.
Update publish 단계에서 필요한 값은 해당 단계의 shell 또는 EAS environment 설정을 통해 명시적으로 주입되어야 한다.
클라이언트 번들에 포함되는 값과 서버/CI에서만 안전해야 하는 secret을 구분한다. 민감한 secret을 OTA JS bundle에 넣으면 안 된다.
하드닝: update job에서 사용되는 environment 이름, EXPO_PUBLIC_* 노출 변수, secret 변수 접근 가능 여부를 release checklist에 포함한다.

6. OTA 후 앱 fail state / 상태 저장소 경계#

OTA는 JavaScript bundle을 바꾸지만 이미 설치된 native storage, SecureStore/Keychain/Keystore 상태, 빌드에 박힌 update header는 그대로 남는다.
인증 Context, SecureStore 접근 옵션, token schema, requireAuthentication, keychain service/access group 변경은 OTA 직후 null token, 무한 로딩, session invalidation처럼 보일 수 있다.
관련 vault 노트 Expo EAS OTA Channel Header Resolution and SecureStore Session Failure Modes와 함께 검토해 “OTA가 네이티브 값을 삭제했다”로 단정하지 말고 JS 로직·옵션·기존 기기 상태의 경계 문제로 진단한다.

7. 롤백과 republish의 한계#

eas update:republish는 이전 update를 새 update group으로 다시 publish하는 성격이며, 이미 불량 update를 다운로드한 클라이언트가 즉시 되돌아간다는 보장은 없다.
expo-updates의 자동 rollback은 제한된 조건, 특히 launch 초기에 치명적 문제가 발생하는 경우에 의존한다.
운영 SOP에는 update group id 기록, 영향 branch/channel, runtimeVersion, 배포 시각, 수동 복구 안내, 새 binary 필요 여부를 포함한다.

8. 네트워크/매니페스트 디버깅 절차#

eas update:list, eas branch:view, eas channel:view로 publish된 update와 channel 연결을 확인한다.
기기 빌드가 실제로 어떤 channel/runtimeVersion/platform을 보내는지 확인한다.
https://u.expo.dev/<project-id> 계열 update request를 프록시나 로그로 확인해 request header와 manifest 응답을 본다.
200/304 여부만 보지 말고 “호환되는 update 없음”, code signing rejection, asset download failure, rollout 조건을 분리한다.
CDN/네트워크 차단 가능성이 있으면 manifest 수신과 asset download를 따로 확인한다.

Release Hardening Checklist#

[ ] CI에 EXPO_TOKEN 또는 동등한 Expo access token이 secret으로 주입된다
[ ] `eas whoami`와 project/account 확인이 publish 전에 실행된다
[ ] prod/staging channel → branch 연결을 `eas channel:view/list`로 확인했다
[ ] update가 의도한 branch와 platform으로 publish된다
[ ] runtimeVersion 정책명이 현재 Expo SDK/EAS CLI 문서와 일치한다
[ ] native 변경 시 runtimeVersion 또는 binary release 전략이 정해져 있다
[ ] code signing private key/certificate 주입 경로가 확인되었다
[ ] EAS Build env와 EAS Update env를 분리해 체크했다
[ ] 클라이언트 번들에 포함될 수 있는 env와 secret-only env를 구분했다
[ ] SecureStore/Auth 상태 schema 변경 시 migration/fallback을 준비했다
[ ] update group id, branch, channel, runtimeVersion을 release log에 기록한다
[ ] republish/rollback SOP와 새 binary 필요 조건을 문서화했다

Cautions#

특정 CLI 에러 문자열은 EAS CLI/Expo SDK 버전에 따라 달라질 수 있으므로 로그 문구 하나만으로 원인을 확정하지 않는다.
fingerprintExperimental 같은 오래된 정책명은 그대로 재사용하지 말고 현재 공식 문서의 runtimeVersion policy 명칭을 확인한다.
환경변수는 “EAS Build에서 됐으니 EAS Update에서도 된다”고 가정하지 않는다.
OTA로 복구 불가능한 native/runtime/code-signing 문제는 새 binary release가 필요할 수 있다.

Sagwan Revalidation 2026-05-15T21:41:44Z#

verdict: ok
note: EAS Update 인증·채널·runtimeVersion 진단 원칙이 여전히 유효함

Sagwan Revalidation 2026-05-16T21:57:11Z#

verdict: ok
note: EAS 토큰·채널·runtimeVersion 진단 원칙이 여전히 유효함

Sagwan Revalidation 2026-05-17T22:19:28Z#

verdict: ok
note: EAS OTA 진단 축과 토큰·채널·런타임 설명은 여전히 유효함

Sagwan Revalidation 2026-05-18T22:46:44Z#

verdict: ok
note: 인증·채널·runtimeVersion 진단 기준이 현재 관행과 모순 없다.

Sagwan Revalidation 2026-05-19T23:09:14Z#

verdict: ok
note: Expo EAS Update 인증·라우팅·runtimeVersion 설명이 현재 관행과 부합함

Sagwan Revalidation 2026-05-20T23:45:32Z#

verdict: ok
note: 인증·채널·runtimeVersion 진단 기준이 현재 관행과 대체로 일치함

Sagwan Revalidation 2026-05-22T00:08:27Z#

verdict: ok
note: 최근 검증 이후 변동 징후 없고 인증·라우팅·runtimeVersion 원칙이 유효함

Sagwan Revalidation 2026-05-23T00:19:17Z#

verdict: ok
note: 인증·라우팅·runtimeVersion 진단 기준이 현재 관행과 충돌하지 않음

Sagwan Revalidation 2026-05-24T00:53:06Z#

verdict: ok
note: 인증·채널·런타임 진단 기준이 현재 EAS Update 관행과 부합함

Sagwan Revalidation 2026-05-25T01:13:01Z#

verdict: ok
note: 핵심 진단축과 EAS Update 라우팅·토큰 권장안은 여전히 유효함

Sagwan Revalidation 2026-05-26T01:15:12Z#

verdict: ok
note: 핵심 진단 축과 권장 하드닝이 현재 EAS Update 관행과 부합함

Sagwan Revalidation 2026-05-27T02:01:08Z#

verdict: ok
note: EAS Update 인증·채널·runtimeVersion 진단 기준은 현재도 유효함

Sagwan Revalidation 2026-05-28T03:05:58Z#

verdict: ok
note: Expo EAS Update 인증·라우팅·runtimeVersion 진단 기준이 여전히 유효함

Sagwan Revalidation 2026-05-29T03:09:41Z#

verdict: ok
note: 전반적 진단축과 하드닝 권장안이 현재 EAS Update 관행과 부합함

Sagwan Revalidation 2026-05-30T03:39:26Z#

verdict: ok
note: EAS Update 인증·라우팅·runtimeVersion 진단 기준은 여전히 유효함

Sagwan Revalidation 2026-05-31T04:14:11Z#

verdict: ok
note: 인증·채널·runtimeVersion 진단 기준이 현재 관행과 부합한다.

Sagwan Revalidation 2026-06-01T07:53:27Z#

verdict: ok
note: EAS Update 인증·채널·런타임 진단 원칙이 여전히 유효함

Sagwan Revalidation 2026-06-02T08:51:16Z#

verdict: ok
note: 핵심 진단축과 runtimeVersion 주의가 현재 EAS Update 관행과 부합함

Sagwan Revalidation 2026-06-03T09:40:18Z#

verdict: ok
note: Expo EAS Update 인증·라우팅·runtimeVersion 진단 기준은 여전히 유효함

Sagwan Revalidation 2026-06-04T10:08:01Z#

verdict: ok
note: 인증·채널·runtimeVersion 진단 기준이 현재 EAS Update 관행과 부합함

Sagwan Revalidation 2026-06-05T10:28:29Z#

verdict: ok
note: 전일 검증 후 변경 신호 없고 인증·라우팅·runtimeVersion 원칙이 유효함