GitHub Actions에서 Docker Hub 이미지를 가져오거나 올릴 때 장기간 유지되는 개인 액세스 토큰(PAT)이나 조직 액세스 토큰(OAT)을 저장하지 않아도 되는 인증 방식이 추가됐다. Docker 조직은 GitHub가 발급한 OpenID Connect(OIDC) 신원 토큰을 바탕으로 워크플로 실행마다 수명이 짧은 Docker 액세스 토큰을 받을 수 있다. 핵심은 빌드나 배포 명령을 바꾸는 것이 아니라, CI/CD 파이프라인의 로그인 단계를 저장형 자격 증명에서 실행 단위 인증으로 교체하는 데 있다.

무엇이 달라졌나

기존 GitHub Actions 워크플로는 Docker Hub에 로그인하기 위해 PAT 또는 OAT를 GitHub Secret에 저장하는 방식이 일반적이었다. 이 토큰은 워크플로가 끝난 뒤에도 유효할 수 있으므로 담당자가 주기적으로 교체해야 한다. 토큰이 노출되면 폐기하기 전까지 비공개 이미지 다운로드, 이미지 업로드 등 토큰에 허용된 작업이 계속 가능하다는 점도 운영 부담이다.

OIDC 연결을 사용하면 GitHub Actions가 현재 실행의 신원을 나타내는 서명된 JWT를 발급한다. 이 토큰에는 저장소, 브랜치, 환경 등 워크플로 실행과 관련된 정보가 포함된다. Docker는 GitHub의 공개 키 정보를 이용해 서명을 검증하고, Docker 관리자가 미리 설정한 규칙과 토큰의 조건이 일치하는지 확인한다. 조건을 통과하면 해당 규칙에 정의된 리소스 범위로 제한된 단기 Docker 액세스 토큰을 반환한다.

발급된 Docker 토큰은 몇 분 안에 만료되며 재사용할 수 없다. 따라서 장기 토큰을 GitHub Secret에 저장하고 교체하는 작업을 줄일 수 있다. 다만 OIDC가 모든 보안 위험을 없애는 것은 아니다. GitHub Actions 워크플로 수정 권한, 브랜치 보호, 실행 환경과 외부 액션의 신뢰성, Docker 규칙 범위가 부적절하면 여전히 예상보다 넓은 권한이 사용될 수 있다.

이용할 수 있는 조직과 적용 범위

Docker가 밝힌 이용 대상은 Docker Team, Docker Business 또는 Docker Hardened Images(DHI) 구독을 사용하는 조직과 Docker Sponsored Open Source Program(DSOS)에 등록된 조직이다. 개인 계정이나 다른 구독 조건에서도 사용할 수 있다고 단정할 수 없으므로, 실제 설정 전에 Docker Home에서 해당 조직에 OIDC connections 메뉴가 표시되는지 확인해야 한다.

이번 기능의 직접적인 대상은 GitHub Actions와 Docker Hub 사이의 인증이다. 로컬 개발 환경이나 GitHub Actions가 아닌 다른 CI 서비스는 계속 PAT 또는 OAT를 사용해야 한다. Docker는 다른 CI 제공자 지원 가능성을 수요에 따라 검토한다는 입장이지만, 구체적인 제공 일정은 발표 내용에 포함되지 않았다.

환경 현재 적용 판단 확인할 사항
GitHub Actions에서 Docker Hub 사용 OIDC 전환 대상 조직 구독, 관리자 권한, 저장소·브랜치 규칙
로컬 개발 환경 PAT 또는 OAT 유지 개발자별 토큰 범위와 교체 정책
GitHub 이외의 CI PAT 또는 OAT 유지 해당 CI가 지원하는 대체 인증 방식
기존 GitHub Actions 워크플로 단계적 전환 가능 OIDC 성공 검증 후 기존 Secret 제거

인증 흐름은 어떻게 동작하나

  1. GitHub Actions 워크플로가 id-token: write 권한으로 GitHub OIDC 토큰을 요청한다.
  2. docker/login-action이 이 토큰을 Docker에 전달한다.
  3. Docker가 토큰 서명과 OIDC subject 조건을 검증한다.
  4. 설정된 규칙과 일치하면 허용된 Docker Hub 리소스 범위의 단기 액세스 토큰을 발급한다.
  5. docker/login-action이 발급된 토큰으로 Docker Hub 로그인을 완료한다.
  6. 이후 docker pull, docker push, docker build 작업은 기존 방식대로 실행된다.

OIDC 연결은 인증 단계만 대체한다. 이미지 구조, 저장소, 레지스트리 사용법, 빌드 명령과 배포 흐름까지 새 체계로 이전하는 기능은 아니다. 따라서 기존 파이프라인의 변경 범위는 비교적 작지만, 로그인 이후에 실행되는 작업이 어느 Docker Hub 리소스에 접근해야 하는지는 규칙 설계 단계에서 정확히 정리해야 한다.

설정할 때 중요한 규칙 범위

Docker Home에서 조직을 선택한 뒤 OIDC 연결을 만들고, 어떤 GitHub 저장소와 브랜치 또는 워크플로가 어떤 Docker Hub 리소스에 접근할 수 있는지 규칙을 구성한다. 연결 하나에는 최대 다섯 개의 규칙을 만들 수 있다. 워크플로가 인증을 요청하면 Docker는 연결에 포함된 각 규칙과 들어온 토큰의 조건을 비교하고, 일치하는 규칙에 따라 접근 권한을 결정한다.

가장 중요한 원칙은 저장소와 브랜치 범위를 필요한 만큼만 좁히는 것이다. 예를 들어 특정 저장소의 main 브랜치만 프로덕션 이미지를 올릴 수 있게 하고, release 계열 브랜치는 별도 이미지 경로만 사용하게 나누는 방식이 가능하다. 저장소의 모든 브랜치를 허용하는 규칙은 기능상 편리하지만, 기능 브랜치나 외부 기여자의 코드가 민감한 이미지에 접근할 가능성을 함께 검토해야 한다. 조직의 모든 저장소를 포괄하는 조건은 관리가 간단해 보여도 권한 범위가 지나치게 넓어질 수 있어 Docker도 권장하지 않는다.

  • 특정 저장소의 main 브랜치: 정식 이미지 배포처럼 접근 주체가 명확해야 하는 작업에 적합하다.
  • 특정 저장소의 release 계열 브랜치: 릴리스 브랜치마다 동일한 배포 권한이 필요한 경우 검토할 수 있다.
  • 특정 저장소의 모든 브랜치: 테스트 이미지 업로드처럼 넓은 허용이 필요한지 먼저 확인해야 한다.
  • 조직의 모든 저장소: 침해 시 영향 범위가 커질 수 있으므로 예외적인 경우가 아니라면 피하는 편이 안전하다.

2026년 7월 15일 이후 생성된 GitHub 저장소는 기본 subject claim에 변경되지 않는 식별자를 사용한다. Docker가 제시한 예시처럼 조직과 저장소 이름 옆에 숫자 식별자가 포함될 수 있다. 저장소 이름만 예상해 규칙을 작성하면 일치하지 않을 수 있으므로, 새 저장소에서는 실제 워크플로가 보낸 subject 값을 확인한 뒤 규칙을 구성해야 한다. 조직이나 저장소 이름 변경에 따른 영향도 이름 기반 조건과 다를 수 있으므로 GitHub의 해당 변경 설명을 함께 확인하는 것이 좋다.

워크플로에서 바꿀 항목

GitHub Actions 워크플로에는 최소한 contents: read와 id-token: write 권한을 명시하고, Docker 로그인 단계에 docker/login-action을 사용한다. 발표 내용상 OIDC 연결에는 docker/login-action v4.5.0 이상이 필요하다. 로그인 입력에는 Docker 조직 이름을 사용자 이름으로 지정하고, Docker Home에서 연결을 만들 때 받은 연결 ID를 DOCKERHUB_OIDC_CONNECTIONID 환경 값으로 전달한다.

id-token: write는 워크플로가 GitHub OIDC 토큰을 요청할 수 있게 하는 권한이다. 이 설정이 GitHub 저장소의 내용을 수정하는 권한을 의미하지는 않지만, 워크플로가 외부 서비스에 자신의 실행 신원을 증명할 수 있게 한다. 따라서 신뢰하지 않는 코드나 검토되지 않은 외부 액션이 동일한 작업 안에서 실행되지 않는지 살펴야 한다. 재사용 워크플로를 쓰고 있다면 실제 토큰을 요청하는 작업에 권한이 전달되는지도 확인 대상이다.

설정 항목 확인 기준
Docker 조직 이름 이미지를 소유하고 OIDC 연결을 만든 조직과 일치하는가
연결 ID 대상 환경과 조직에 맞는 값을 사용했는가
docker/login-action 버전 OIDC 연결을 지원하는 v4.5.0 이상인가
id-token: write 토큰을 요청하는 작업에 필요한 범위로 부여됐는가
Docker 리소스 권한 pull만 필요한 작업에 push 권한까지 주지 않았는가

안전하게 이전하는 순서

  1. 현재 사용처를 조사한다. 어떤 저장소와 워크플로가 PAT 또는 OAT를 사용하고 있으며, 각각 pull과 push 중 어떤 권한이 필요한지 구분한다.
  2. OIDC 연결과 최소 범위 규칙을 만든다. 처음부터 조직 전체를 허용하지 말고 저장소와 브랜치가 명확한 작업 하나로 시작한다.
  3. 워크플로 로그인 단계만 변경한다. 빌드와 배포 명령은 유지해 인증 변경으로 인한 문제를 분리해서 확인한다.
  4. 실제 실행으로 검증한다. 이미지 가져오기와 업로드가 필요한 범위에서 성공하는지 확인하고, 허용하지 않은 브랜치에서는 인증이 거부되는지도 시험한다.
  5. 실패 정보를 점검한다. Docker Home의 OIDC 연결 페이지에 있는 Failures 탭에서 들어온 subject claim을 확인해 규칙 불일치 원인을 찾는다.
  6. 성공한 뒤 기존 Secret을 제거한다. OIDC 경로를 충분히 검증하기 전에 PAT나 OAT를 먼저 삭제하면 배포가 중단될 수 있다.
  7. 남은 장기 토큰을 추적한다. 같은 토큰이 다른 워크플로, 로컬 환경 또는 외부 CI에서 사용되는지 확인한 후 폐기 여부를 결정한다.

기존 PAT와 OAT는 계속 작동하므로 모든 워크플로를 한 번에 바꿀 필요는 없다. 저장형 토큰을 먼저 삭제했다가 문제가 생겼을 때 다시 발급하는 방식보다, OIDC 인증을 병행해 성공을 확인한 뒤 기존 자격 증명을 제거하는 순서가 안전하다. 단, 병행 기간이 불필요하게 길어지면 장기 토큰 위험도 그대로 남으므로 전환 완료 기준과 제거 시점을 정해 두는 것이 좋다.

누가 우선 검토할 만한가

여러 GitHub Actions 파이프라인에서 Docker Hub 이미지를 배포하며 토큰 교체와 권한 감사를 반복하는 팀은 우선 검토할 가치가 크다. 저장소 수가 늘수록 Secret별 소유자, 만료 및 교체 이력을 관리하기 어려워지기 때문이다. 브랜치별로 이미지 업로드 권한을 분리하려는 팀도 OIDC subject 기반 규칙의 이점을 얻을 수 있다.

학생, 연구자, 개인 개발자는 먼저 이용 자격을 확인해야 한다. 지원되는 Docker 조직 구독이나 DSOS 등록 조건에 해당하지 않으면 이번 기능을 바로 적용하지 못할 수 있다. 소규모 프로젝트에서 장기 토큰 하나를 제한된 권한으로 관리하고 있다면 전환 효과가 크지 않을 수도 있다. 반대로 공개 저장소에서 자동으로 이미지를 배포하거나 여러 사람이 워크플로를 수정한다면, 토큰 노출 가능성과 브랜치 권한을 기준으로 검토할 필요가 있다.

도입 전 체크포인트

  • 현재 Docker 조직이 Team, Business, DHI 또는 DSOS 대상에 해당하는가
  • OIDC 연결을 만들고 규칙을 관리할 수 있는 조직 관리자 권한이 있는가
  • 각 워크플로에 필요한 Docker Hub 저장소와 pull·push 권한을 구분했는가
  • main, release, 태그, 환경 등 실제 배포 조건을 subject 규칙으로 충분히 좁힐 수 있는가
  • 새 GitHub 저장소의 변경 불가능한 식별자가 포함된 subject 형식을 확인했는가
  • docker/login-action 버전과 id-token: write 권한을 검토했는가
  • 포크 기반 풀 리퀘스트나 외부 기여 코드가 인증 단계에 도달할 수 있는지 확인했는가
  • OIDC 실패 시 Failures 탭과 GitHub Actions 로그를 확인할 담당자가 정해져 있는가
  • 기존 PAT 또는 OAT가 다른 환경에서도 사용되는지 파악했는가
  • 검증 완료 후 GitHub Secret과 사용하지 않는 장기 토큰을 제거할 절차가 있는가

기존 방식과 비교할 때의 선택 기준

비교 항목 PAT·OAT GitHub Actions OIDC 연결
자격 증명 수명 장기간 유지될 수 있음 실행마다 발급되며 몇 분 안에 만료
GitHub Secret 저장 필요 Docker 장기 토큰 저장은 불필요
교체 작업 수동 관리 필요 실행별 단기 토큰으로 대체
접근 조건 토큰에 지정된 범위 중심 저장소·브랜치 등 실행 신원과 Docker 규칙을 함께 검사
지원 환경 로컬과 다양한 CI에서 사용 가능 현재 발표 범위는 GitHub Actions
기존 빌드 명령 그대로 사용 인증 이후 명령은 그대로 사용

선택의 핵심은 단순히 OIDC가 더 새로운 기술인지가 아니다. GitHub Actions에서 Docker Hub 인증을 반복하고 장기 토큰 교체와 감사가 부담이라면 전환 효과가 분명하다. 반면 로컬 개발이나 다른 CI가 중심이라면 PAT와 OAT 관리가 계속 필요하므로 전체 자격 증명 체계가 한 번에 단순해지는 것은 아니다. 또한 구독 조건에 따른 실제 이용 가능 여부와 비용은 조직의 현재 계약 및 Docker의 최신 안내에서 확인해야 한다.

출처와 검증

기능 지원 대상, 인증 흐름, 규칙 수, docker/login-action 요구 버전과 이전 절차는 Docker의 발표 내용을 기준으로 정리했다. 적용 전에는 조직의 OIDC connections 메뉴, 최신 Docker 문서, GitHub Actions가 전송한 실제 subject claim을 함께 확인해야 한다.

Docker Blog: Docker OIDC connections for GitHub Actions available for Docker Orgs