DEVOPS

Docker + GitHub Actions CI/CD — GHCR·OIDC 배포

junetapa 2026. 10. 30 업데이트 12 min read

Docker 이미지를 만들고 GitHub Actions로 테스트·빌드·배포까지 잇는 흐름을 2026년 10월 기준으로 다시 정리했다. Dockerfile 레이어 순서와 .dockerignore, Compose 파일의 바뀐 규칙(version 줄), PR마다 도는 CI, GHCR에 이미지를 올리고 출처 증명(attestation)을 붙이는 CD, 장기 키 없이 AWS에 배포하는 OIDC까지 공식 문서와 각 액션의 최신 릴리스로 맞췄다.

2026년에 바뀐 것 — 액션 판과 Node 24

예전 예제를 그대로 붙여 넣었을 때 워크플로가 깨지는 가장 흔한 이유는 액션의 메이저 판이다. GitHub 변경 기록에 따르면 2026년 9월 23일부터 GitHub Actions 러너에서 Node 20을 더 쓸 수 없고, 임시로 열어 두던 ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION 우회도 막혔다. 러너는 JavaScript 액션을 Node 24로 돌린다. Node 20 시절에 묶인 옛 메이저 판을 쓰고 있다면 Node 24를 지원하는 최신 판으로 올려야 한다.

아래는 이 글의 예제가 쓰는 액션과 2026-10-30에 각 저장소 릴리스로 확인한 최신 판이다. 워크플로에는 메이저 판(@v7)만 적어도 되지만, 공급망 위험을 줄이려면 커밋 SHA로 고정하는 방법도 있다. GitHub의 AWS OIDC 문서 예제도 SHA로 고정해 적는다.

액션최신 판(릴리스 날짜)이 글에서
actions/checkoutv7.0.1 (2026-07-20)@v7
actions/setup-nodev7.1.0 (2026-10-08)@v7
docker/setup-buildx-actionv4.4.1 (2026-09-16)@v4
docker/login-actionv4.7.0 (2026-10-23)@v4
docker/metadata-actionv6.2.0 (2026-07-02)@v6
docker/build-push-actionv7.4.0 (2026-09-15)@v7
actions/attestv4.2.2 (2026-08-04)@v4
aws-actions/configure-aws-credentialsv6.3.0 (2026-09-15)@v6
예전 정보 바로잡기

이 글의 예전 판은 «2026-06-02부터 Node 24 강제», «액션 핀은 @v5 이상이면 충분»이라고 적었다. 확인되는 공식 날짜는 Node 20 제거일(2026-09-23)이고, 지금 최신 메이저는 위 표와 같다. 출처 증명 액션도 actions/attest-build-provenance README가 v4부터 actions/attest를 감싼 것뿐이니 새 구현은 actions/attest를 쓰라고 안내한다.

Docker 핵심 개념과 명령

Docker는 앱과 실행에 필요한 파일을 이미지 하나로 묶고, 그 이미지를 어디서나 같은 방식으로 컨테이너로 실행하게 해 준다. 개발 PC, CI 러너, 운영 서버가 같은 이미지를 쓰므로 «내 PC에서는 되는데»가 줄고, 문제가 생기면 이전 이미지 태그(또는 다이제스트)로 되돌리기 쉽다.

용어설명
Image컨테이너 실행에 필요한 파일 묶음(읽기 전용 레이어의 쌓임)
Container이미지로 실행 중인 인스턴스(한 이미지로 여러 개)
Dockerfile이미지를 만드는 명령 목록
Registry이미지를 올리고 받는 저장소(Docker Hub, GHCR, ECR 등)
Compose여러 컨테이너를 파일 하나로 정의하고 함께 올리는 도구
Digest이미지 내용의 해시(sha256:…) — 태그와 달리 바뀌지 않음
bash
# 이미지
docker build -t myapp:1.0 .           # 현재 폴더 Dockerfile로 빌드
docker image ls                       # 이미지 목록
docker pull node:24-alpine            # 이미지 받기

# 컨테이너
docker run -d -p 3000:3000 myapp:1.0  # 백그라운드 실행 + 포트 연결
docker ps                             # 실행 중 컨테이너
docker logs -f <컨테이너>             # 로그 따라 보기
docker exec -it <컨테이너> sh         # 안으로 들어가기(alpine은 bash 대신 sh)
도커파일과 이미지, 컨테이너로 이어지는 도커 핵심 개념을 나타낸 도해
설계도 → 만들어진 것 → 돌아가는 것 — 셋의 관계다.

Dockerfile — 레이어 순서와 멀티 스테이지

Dockerfile의 명령은 위에서부터 레이어로 쌓이고, 어떤 레이어가 바뀌면 그 아래 레이어는 모두 다시 만든다. 그래서 잘 바뀌지 않는 것(베이스 이미지, 의존성 목록)을 위에, 자주 바뀌는 것(소스 코드)을 아래에 둔다. 아래 예는 의존성 설치 → 빌드 → 실행 단계를 나눈 멀티 스테이지 빌드다. 마지막 단계에는 빌드 도구 없이 실행에 필요한 파일만 남는다.

dockerfile
# syntax=docker/dockerfile:1
# 1단계: 의존성 설치(빌드 도구 포함)
FROM node:24-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci

# 2단계: 빌드 후 실행용 의존성만 남기기
FROM node:24-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build && npm prune --omit=dev

# 3단계: 실행
FROM node:24-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -S app && adduser -S app -G app
COPY --from=builder --chown=app:app /app/dist ./dist
COPY --from=builder --chown=app:app /app/node_modules ./node_modules
COPY --from=builder --chown=app:app /app/package.json ./
USER app
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
    CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

RUN --mount=type=cache는 BuildKit 캐시 마운트로, npm 내려받기 캐시를 이미지에 넣지 않고 빌드 사이에만 재사용한다. USER는 파일 복사 뒤에 두어도 되고 앞에 두어도 되지만, 복사한 파일 소유자를 --chown으로 맞춰야 실행 사용자가 읽을 수 있다.

빌드 맥락(context)에 불필요한 파일이 들어가면 빌드가 느려지고 비밀 값이 이미지에 섞일 수 있다. .dockerignore로 먼저 걸러 낸다.

.dockerignore
node_modules
dist
.git
.github
.env
.env.*
*.log
coverage
레이어 캐시를 살리는 도커파일 작성 순서를 정리한 도해
자주 바뀌는 것을 뒤로 미루면 빌드가 크게 빨라진다.

Docker Compose — 여러 컨테이너 묶기

실제 서비스는 앱 서버, 데이터베이스, 캐시처럼 여러 컨테이너로 이루어진다. Compose는 이를 파일 하나로 정의한다. 예전 예제 맨 위에 흔히 있던 version: '3.9' 줄은 지금 Compose 사양에서 «참고용일 뿐이며, 쓰면 더 이상 쓰지 않는다는 경고가 나온다»고 되어 있어 빼는 것이 맞다. 아래 예는 데이터베이스 비밀번호를 파일 비밀(secrets)로 넘기고, 데이터베이스가 건강해진 뒤에 앱을 띄운다.

compose.yaml
services:
  app:
    build:
      context: .
      target: runner
    image: ghcr.io/my-org/myapp:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: app
      POSTGRES_DB: mydb
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d mydb"]
      interval: 10s
      timeout: 5s
      retries: 5

  cache:
    image: redis:7-alpine
    restart: unless-stopped

secrets:
  db_password:
    file: ./secrets/db_password.txt

volumes:
  pgdata:

Compose는 프로젝트마다 기본 네트워크를 만들어 주므로 서비스 이름(db, cache)이 그대로 호스트 이름이 된다. 네트워크를 따로 나눌 이유가 없다면 networks 정의는 생략해도 된다. 데이터 볼륨, 백업, 로그 관리처럼 Compose를 오래 운영할 때의 내용은 Docker Compose 멀티 컨테이너 운영 가이드에 따로 정리했다.

CI 워크플로 — PR마다 테스트

CI는 «합치기 전에 깨진 것을 잡는» 단계다. PR이 열리거나 갱신될 때마다 린트와 테스트를 돌리고, 저장소 설정의 브랜치 보호(필수 상태 검사)에 이 작업을 걸어 두면 실패한 PR은 합칠 수 없다. 워크플로 맨 위 permissions로 토큰 권한을 읽기만으로 줄여 두는 것이 기본이다.

yaml -- .github/workflows/ci.yml
name: CI

on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test

  docker-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4
      - name: 이미지가 빌드되는지만 확인(푸시 안 함)
        uses: docker/build-push-action@v7
        with:
          context: .
          push: false
          cache-from: type=gha
          cache-to: type=gha,mode=max

두 번째 작업은 Dockerfile이 깨지지 않았는지 PR 단계에서 확인한다. type=gha는 Docker 문서가 GitHub Actions 안에서 권하는 캐시 저장 방식으로, GitHub Actions 캐시에 BuildKit 캐시를 저장한다. 같은 scope를 쓰는 빌드끼리는 캐시를 덮어쓰므로, 이미지가 여러 개라면 scope=이미지이름처럼 나눠 준다. 캐시는 GitHub 사용 한도와 정리 규칙을 따르므로 오래 쓰지 않은 항목은 지워진다.

CD 워크플로 — GHCR 푸시와 출처 증명

main에 합쳐지면 이미지를 빌드해 GitHub Container Registry(GHCR)에 올린다. GHCR은 워크플로에 자동으로 들어오는 GITHUB_TOKEN과 packages: write 권한만으로 로그인할 수 있어 Docker Hub 계정 비밀 값을 따로 둘 필요가 없다. 빌드 뒤에는 actions/attest로 이미지 다이제스트에 출처 증명을 붙인다. README에 따르면 다른 입력이 없으면 SLSA 빌드 출처(provenance) 증명을 만든다.

yaml -- .github/workflows/deploy.yml
name: CD

on:
  push:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write          # GHCR 푸시
      id-token: write          # 출처 증명 서명용 OIDC 토큰
      attestations: write      # 증명 저장
      artifact-metadata: write # 저장 기록(조직 저장소)
    outputs:
      digest: ${{ steps.push.outputs.digest }}
    steps:
      - uses: actions/checkout@v7
      - uses: docker/setup-buildx-action@v4

      - name: GHCR 로그인
        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: 태그·라벨
        id: meta
        uses: docker/metadata-action@v6
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha
            type=raw,value=latest,enable={{is_default_branch}}

      - name: 빌드·푸시
        id: push
        uses: docker/build-push-action@v7
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: 출처 증명
        uses: actions/attest@v4
        with:
          subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          subject-digest: ${{ steps.push.outputs.digest }}
          push-to-registry: true
태그를 넣지 않는 이유

subject-name에는 태그 없이 이미지 이름만 적는다. 어떤 이미지를 증명하는지는 subject-digest가 정하기 때문이다. 증명은 GitHub CLI의 gh attestation verify 명령으로 확인한다. 여러 아키텍처(linux/amd64,linux/arm64)를 한 번에 빌드하면 시간이 늘어나므로, 실제로 arm64 서버가 없다면 한 플랫폼만 빌드해도 된다.

푸시와 테스트, 이미지 빌드, 배포로 이어지는 깃허브 액션스 파이프라인을 나타낸 도해
코드를 밀어 넣으면 나머지가 자동으로 돈다.

재사용 워크플로, 환경별 승인, 동시 실행 제어처럼 파이프라인을 더 키우는 방법은 GitHub Actions CI/CD 고급 워크플로우와 자동화된 테스트·배포 파이프라인에서 이어서 다룬다.

배포 — 서버 Compose와 AWS OIDC

직접 운영하는 서버: Compose로 교체

VM이나 사내 서버라면 서버에서 GHCR의 새 이미지를 받아 Compose로 교체하는 방식이 단순하다. 서버에서 GHCR에 로그인할 때는 패키지 읽기 권한만 가진 토큰을 쓴다. docker compose up --wait는 공식 설명대로 서비스가 «실행 중이거나 건강한» 상태가 될 때까지 기다리고, --no-deps는 연결된 서비스를 다시 띄우지 않는다.

bash -- 서버 쪽 deploy.sh
#!/usr/bin/env bash
set -euo pipefail

# 미리 docker login ghcr.io 를 마친 상태
docker compose pull app

# 앱만 새 이미지로 교체하고 healthcheck 통과까지 기다림(최대 120초)
docker compose up -d --no-deps --wait --wait-timeout 120 app

# 쓰지 않는 이미지 정리
docker image prune -f

이 방식은 컨테이너를 바꾸는 순간 짧은 끊김이 생길 수 있다. 끊김 없이 바꾸려면 앞단에 리버스 프록시를 두고 새 컨테이너가 건강해진 뒤 트래픽을 옮기거나, 오케스트레이터(ECS, Kubernetes)의 롤링 배포를 쓴다.

AWS: 장기 키 없이 OIDC로

AWS에 배포할 때는 액세스 키를 GitHub 비밀 값에 넣지 않는다. GitHub 문서 순서대로 IAM에 OIDC 공급자(https://token.actions.githubusercontent.com, 대상 sts.amazonaws.com)를 등록하고, 역할의 신뢰 정책에서 어떤 저장소·브랜치·환경만 이 역할을 쓸 수 있는지 sub 조건으로 좁힌다. 문서는 저장소 전체(repo:조직/저장소:*)보다 특정 브랜치나 환경으로 좁히라고 권한다.

json -- IAM 역할 신뢰 정책 조건
"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:my-org/myapp:environment:prod"
  }
}
yaml -- deploy.yml 이어서
  deploy:
    needs: build-and-push
    runs-on: ubuntu-latest
    environment: prod
    permissions:
      id-token: write   # OIDC 토큰 요청
      contents: read
    steps:
      - name: AWS 자격 증명(OIDC)
        uses: aws-actions/configure-aws-credentials@v6
        with:
          role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
          aws-region: ap-northeast-2

      - name: ECS 서비스 새로 배포
        run: |
          aws ecs update-service \
            --cluster prod \
            --service myapp \
            --force-new-deployment

--force-new-deployment는 태스크 정의를 바꾸지 않고 태스크를 새로 띄운다. 태스크 정의가 latest처럼 움직이는 태그를 가리킬 때만 새 이미지를 받으므로, 되돌리기 쉬운 배포를 원하면 빌드 단계에서 나온 다이제스트로 태스크 정의를 새로 등록하는 방식을 고려한다. 작업에 environment: prod를 걸면 저장소 설정의 환경 보호 규칙(승인자 등)도 함께 적용된다.

정리 — 점검표

점검확인할 것
액션 판Node 24를 지원하는 최신 메이저인가(위 표) · 가능하면 SHA 고정
Dockerfile의존성 목록을 소스보다 먼저 복사하는가 · 멀티 스테이지 · 비루트 사용자
.dockerignorenode_modules·.git·.env가 빌드 맥락에서 빠지는가
Composeversion 줄을 뺐는가 · 비밀번호를 파일 비밀로 넘기는가 · healthcheck + service_healthy
CIPR마다 테스트와 이미지 빌드 확인 · 필수 상태 검사에 연결
CDGHCR + GITHUB_TOKEN · 작업별 최소 권한 · 다이제스트에 출처 증명
캐시type=gha · 이미지가 여럿이면 scope 나누기
배포AWS는 OIDC + 좁힌 sub 조건 · 서버는 --wait로 건강 확인

처음부터 모든 단계를 넣을 필요는 없다. CI(테스트) → 이미지 빌드 확인 → GHCR 푸시 → 배포 순서로 하나씩 붙이고, 각 단계가 실패했을 때 무엇이 멈추는지 확인하며 넓히는 편이 문제를 찾기 쉽다. 이미지 취약점 검사(예: Trivy 액션)나 배포 알림은 그다음에 더한다.

Docker와 GitHub Actions CI/CD 대표 그림 — 왼쪽에 제목 글자가 있고, 오른쪽에 컨테이너 상자가 검사 관문을 지나 서버로 이어지는 장면
Docker + GitHub Actions CI/CD — GHCR·OIDC 배포.

자주 묻는 것

Compose 파일의 version 줄은 지워도 되나요?

지워도 됩니다. Docker 문서의 Compose 사양은 최상위 version 속성이 하위 호환을 위한 참고용일 뿐이며, 쓰면 더 이상 쓰지 않는다는 경고가 나온다고 설명합니다.

GHCR에 올릴 때 별도 토큰을 만들어야 하나요?

같은 저장소의 워크플로에서 올린다면 자동으로 들어오는 GITHUB_TOKEN과 packages: write 권한으로 로그인할 수 있습니다. 운영 서버에서 이미지를 받을 때는 패키지 읽기 권한만 가진 토큰을 따로 씁니다.

actions/attest-build-provenance와 actions/attest는 무엇이 다른가요?

attest-build-provenance README는 v4가 actions/attest를 감싼 것뿐이며 새 구현은 actions/attest를 쓰라고 안내합니다. actions/attest는 다른 입력이 없으면 SLSA 빌드 출처 증명을 만듭니다.

Node 20을 쓰는 옛 액션은 이제 동작하지 않나요?

GitHub 변경 기록에 따르면 2026년 9월 23일부터 러너에서 Node 20을 쓸 수 없고 임시 우회 설정도 막혔습니다. Node 24를 지원하는 최신 판으로 올려야 합니다.

참고 자료

  1. GitHub Changelog. Node 20 is no longer available in GitHub Actions(2026-09-23 · 2026-10-30 확인). github.blog
  2. GitHub Docs. Configuring OpenID Connect in Amazon Web Services — 공급자·대상·sub 조건·권한(2026-10-30 확인). docs.github.com
  3. actions/attest README — 컨테이너 이미지 증명 예, 권한, 기본 SLSA 출처 증명(2026-10-30 확인). github.com
  4. actions/attest-build-provenance README — v4는 actions/attest를 감쌈(2026-10-30 확인). github.com
  5. Docker Docs. GitHub Actions cache(type=gha) — mode·scope·정리 규칙(2026-10-30 확인). docs.docker.com
  6. Docker Docs. Compose file — version and name(2026-10-30 확인). docs.docker.com
  7. Docker Docs. docker compose up — --wait·--wait-timeout·--no-deps(2026-10-30 확인). docs.docker.com
  8. 각 액션 저장소 최신 릴리스 — checkout·setup-node·setup-buildx·login·metadata·build-push·attest·configure-aws-credentials(GitHub Releases · 2026-10-30 확인). github.com
DockerGitHub ActionsCI/CDDockerfileDocker Compose자동 배포DevOps
junetapa(박준철)
개발자가 아니라 쓰는 사람. IT 현장 27년의 기준으로 AI 도구를 고르고 기록한다.
Twitter Facebook URL 복사