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/checkout | v7.0.1 (2026-07-20) | @v7 |
| actions/setup-node | v7.1.0 (2026-10-08) | @v7 |
| docker/setup-buildx-action | v4.4.1 (2026-09-16) | @v4 |
| docker/login-action | v4.7.0 (2026-10-23) | @v4 |
| docker/metadata-action | v6.2.0 (2026-07-02) | @v6 |
| docker/build-push-action | v7.4.0 (2026-09-15) | @v7 |
| actions/attest | v4.2.2 (2026-08-04) | @v4 |
| aws-actions/configure-aws-credentials | v6.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:…) — 태그와 달리 바뀌지 않음 |
# 이미지 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의 명령은 위에서부터 레이어로 쌓이고, 어떤 레이어가 바뀌면 그 아래 레이어는 모두 다시 만든다. 그래서 잘 바뀌지 않는 것(베이스 이미지, 의존성 목록)을 위에, 자주 바뀌는 것(소스 코드)을 아래에 둔다. 아래 예는 의존성 설치 → 빌드 → 실행 단계를 나눈 멀티 스테이지 빌드다. 마지막 단계에는 빌드 도구 없이 실행에 필요한 파일만 남는다.
# 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로 먼저 걸러 낸다.
node_modules dist .git .github .env .env.* *.log coverage
Docker Compose — 여러 컨테이너 묶기
실제 서비스는 앱 서버, 데이터베이스, 캐시처럼 여러 컨테이너로 이루어진다. Compose는 이를 파일 하나로 정의한다. 예전 예제 맨 위에 흔히 있던 version: '3.9' 줄은 지금 Compose 사양에서 «참고용일 뿐이며, 쓰면 더 이상 쓰지 않는다는 경고가 나온다»고 되어 있어 빼는 것이 맞다. 아래 예는 데이터베이스 비밀번호를 파일 비밀(secrets)로 넘기고, 데이터베이스가 건강해진 뒤에 앱을 띄운다.
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로 토큰 권한을 읽기만으로 줄여 두는 것이 기본이다.
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) 증명을 만든다.
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: truesubject-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는 연결된 서비스를 다시 띄우지 않는다.
#!/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:조직/저장소:*)보다 특정 브랜치나 환경으로 좁히라고 권한다.
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
"token.actions.githubusercontent.com:sub": "repo:my-org/myapp:environment:prod"
}
} 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 | 의존성 목록을 소스보다 먼저 복사하는가 · 멀티 스테이지 · 비루트 사용자 |
| .dockerignore | node_modules·.git·.env가 빌드 맥락에서 빠지는가 |
| Compose | version 줄을 뺐는가 · 비밀번호를 파일 비밀로 넘기는가 · healthcheck + service_healthy |
| CI | PR마다 테스트와 이미지 빌드 확인 · 필수 상태 검사에 연결 |
| CD | GHCR + GITHUB_TOKEN · 작업별 최소 권한 · 다이제스트에 출처 증명 |
| 캐시 | type=gha · 이미지가 여럿이면 scope 나누기 |
| 배포 | AWS는 OIDC + 좁힌 sub 조건 · 서버는 --wait로 건강 확인 |
처음부터 모든 단계를 넣을 필요는 없다. CI(테스트) → 이미지 빌드 확인 → GHCR 푸시 → 배포 순서로 하나씩 붙이고, 각 단계가 실패했을 때 무엇이 멈추는지 확인하며 넓히는 편이 문제를 찾기 쉽다. 이미지 취약점 검사(예: Trivy 액션)나 배포 알림은 그다음에 더한다.
자주 묻는 것
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를 지원하는 최신 판으로 올려야 합니다.
참고 자료
- GitHub Changelog. Node 20 is no longer available in GitHub Actions(2026-09-23 · 2026-10-30 확인). github.blog
- GitHub Docs. Configuring OpenID Connect in Amazon Web Services — 공급자·대상·sub 조건·권한(2026-10-30 확인). docs.github.com
- actions/attest README — 컨테이너 이미지 증명 예, 권한, 기본 SLSA 출처 증명(2026-10-30 확인). github.com
- actions/attest-build-provenance README — v4는 actions/attest를 감쌈(2026-10-30 확인). github.com
- Docker Docs. GitHub Actions cache(type=gha) — mode·scope·정리 규칙(2026-10-30 확인). docs.docker.com
- Docker Docs. Compose file — version and name(2026-10-30 확인). docs.docker.com
- Docker Docs. docker compose up — --wait·--wait-timeout·--no-deps(2026-10-30 확인). docs.docker.com
- 각 액션 저장소 최신 릴리스 — checkout·setup-node·setup-buildx·login·metadata·build-push·attest·configure-aws-credentials(GitHub Releases · 2026-10-30 확인). github.com