😵 프롤로그: "제 로컬에선 잘 됐는데요?"

친구야, 우리 솔직해지자.
개발하다 보면 이런 대사 한 번쯤 해봤지?

이 세 문장은 사실 같은 병의 증상이야. 병명은 수동 배포 증후군.
사람 손이 들어가는 곳엔 반드시 실수가 끼고, 실수는 꼭 금요일 저녁에 터진다.

그래서 나온 게 CI/CD고, 그중에서도 GitHub Actions는
"GitHub 쓰고 있으면 그냥 바로 시작 가능"이라는 사기급 접근성을 가진 도구야.

이 글에서는 개념 → 문법 → 실전 워크플로 → 캐싱/시크릿 → 배포 → 비용/보안까지
진짜 실무에서 쓰는 순서대로 쭉 훑어줄게. 커피 한 잔 챙겨와. ☕

🧠 1장. CI/CD, 용어부터 제대로 정리하자

CI (Continuous Integration, 지속적 통합)

코드를 자주, 작게 통합하고, 통합할 때마다 자동으로 빌드+테스트하는 습관이야.
목적은 단순해. "깨진 코드를 최대한 빨리 발견한다."

3개월 동안 브랜치 혼자 파고들다가 머지하면 그건 통합이 아니라 충돌 대잔치지.
CI는 "하루에 한 번 이상 main과 만나라"는 문화 + 그걸 받쳐주는 자동화 도구의 조합이야.

CD, 사실 두 가지 뜻이 있다

왜 GitHub Actions인가?

🧩 2장. 구조 해부 — Workflow, Job, Step, Action

GitHub Actions는 러시아 인형(마트료시카) 구조야. 이 계층만 이해하면 YAML이 갑자기 읽혀.

용어 정리표

✍️ 3장. 첫 워크플로 — Hello, Automation

레포 루트에 .github/workflows/ci.yml 만들고 이거 붙여넣어 봐.

name: CI

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  hello:
    runs-on: ubuntu-latest
    steps:
      - name: 코드 내려받기
        uses: actions/checkout@v4

      - name: 인사하기
        run: echo "안녕 $GITHUB_ACTOR! 커밋 $GITHUB_SHA 확인했다."

      - name: 파일 구경
        run: ls -al

push 하고 레포의 Actions 탭 열어봐. 초록 체크 뜨면 성공. 🎉
이게 CI/CD의 첫 심장 박동이야.

각 줄이 하는 일

🎯 4장. 트리거(on) 총정리 — 언제 돌릴 것인가

자주 쓰는 이벤트

on:
  # 1) 푸시 — 경로 필터로 모노레포 최적화
  push:
    branches: [ main ]
    paths:
      - 'apps/web/**'
      - '!**/*.md'          # 문서만 바뀌면 실행 안 함

  # 2) PR — 어떤 액션에 반응할지 지정
  pull_request:
    types: [ opened, synchronize, reopened ]

  # 3) 태그 푸시 — 릴리즈 배포용
  push:
    tags: [ 'v*.*.*' ]

  # 4) 스케줄 — 크론 (UTC 기준!)
  schedule:
    - cron: '0 18 * * *'     # 매일 한국시간 03:00

  # 5) 수동 실행 + 입력값
  workflow_dispatch:
    inputs:
      environment:
        description: '배포 대상'
        type: choice
        options: [ staging, production ]
        default: staging

  # 6) 다른 워크플로가 끝난 뒤
  workflow_run:
    workflows: [ "CI" ]
    types: [ completed ]

pull_request vs pull_request_target

외부 포크에서 온 PR은 시크릿에 접근할 수 없어(의도된 보안 설계).
pull_request_target은 베이스 브랜치 권한으로 실행돼서 시크릿을 쓸 수 있는데,
여기서 PR 코드를 체크아웃해 실행하면 시크릿 유출 취약점이 돼.

🛠️ 5장. 실전 워크플로 ① Node.js 앱 CI

이제 진짜 쓸 만한 걸 만들어보자. 린트 → 타입체크 → 테스트 → 빌드.

name: Node CI

on:
  push:
    branches: [ main ]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  quality:
    runs-on: ubuntu-latest
    timeout-minutes: 15

    strategy:
      fail-fast: false
      matrix:
        node: [ 18, 20, 22 ]

    steps:
      - uses: actions/checkout@v4

      - name: Node ${{ matrix.node }} 세팅
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node }}
          cache: 'npm'          # 내부적으로 캐시 처리

      - name: 의존성 설치
        run: npm ci              # install 아님! ci 임

      - name: 린트
        run: npm run lint

      - name: 타입 체크
        run: npx tsc --noEmit

      - name: 테스트 + 커버리지
        run: npm test -- --coverage

      - name: 빌드
        run: npm run build

      - name: 빌드 결과 저장
        if: matrix.node == 20
        uses: actions/upload-artifact@v4
        with:
          name: web-dist
          path: dist/
          retention-days: 7

여기서 꼭 챙길 3가지

⚡ 6장. 캐싱 — 파이프라인 속도를 2배로

CI가 느리면 사람들은 CI를 안 본다. 그러면 CI는 죽는다.
그래서 캐싱은 기능이 아니라 문화 유지 장치야.

      - name: 의존성 캐시
        uses: actions/cache@v4
        with:
          path: |
            ~/.npm
            .next/cache
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-node-

캐시 키 설계 원칙

캐시 vs 아티팩트, 헷갈리지 말자

🔐 7장. 시크릿과 환경 — 비밀은 코드에 두지 않는다

배포엔 필연적으로 비밀이 붙어. API 키, SSH 키, 레지스트리 토큰…
이걸 YAML에 하드코딩하는 순간 깃 히스토리에 영원히 박제돼.

시크릿 3계층

jobs:
  deploy-prod:
    runs-on: ubuntu-latest
    environment:
      name: production          # 승인/보호 규칙 적용
      url: https://example.com
    steps:
      - uses: actions/checkout@v4
      - name: 배포
        env:
          API_KEY: ${{ secrets.PROD_API_KEY }}
          DB_URL:  ${{ secrets.PROD_DB_URL }}
        run: ./scripts/deploy.sh

GITHUB_TOKEN과 권한 최소화

모든 실행마다 자동으로 GITHUB_TOKEN이 발급돼. 편한데, 기본 권한이 넓으면 위험해.

permissions:
  contents: read        # 기본은 읽기만
  # 필요한 Job에서만 아래처럼 승격
jobs:
  release:
    permissions:
      contents: write
      packages: write
      id-token: write   # OIDC용

🌟 장기 키를 없애는 법: OIDC

AWS/GCP/Azure에 배포할 때 Access Key를 시크릿에 저장하는 시대는 끝났어.
GitHub이 발급한 짧은 수명의 ID 토큰으로 클라우드 역할을 직접 맡는(assume) 방식이 표준이야.

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-deploy
          aws-region: ap-northeast-2
      - run: aws s3 sync ./dist s3://my-bucket --delete

🐳 8장. 실전 워크플로 ② Docker 빌드 & GHCR 푸시

컨테이너 시대의 CD는 대체로 "이미지 만들어 레지스트리에 올리고, 서버가 그걸 당겨간다"로 정리돼.

name: Build & Push Image

on:
  push:
    branches: [ main ]
    tags: [ 'v*.*.*' ]

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

jobs:
  docker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Buildx 셋업
        uses: docker/setup-buildx-action@v3

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

      - name: 태그/라벨 자동 생성
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=sha,format=short

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

포인트 해설

🚢 9장. 실전 워크플로 ③ 배포 패턴 4종

① 정적 사이트 → GitHub Pages

name: Deploy Pages

on:
  push:
    branches: [ main ]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci && npm run build
      - uses: actions/upload-pages-artifact@v3
        with: { path: ./dist }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

② 리눅스 서버 → SSH 배포

      - name: SSH로 배포
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            set -e
            cd /srv/app
            docker compose pull
            docker compose up -d --remove-orphans
            docker image prune -f

③ Kubernetes → 이미지 태그 교체

      - name: kubeconfig 준비
        run: |
          mkdir -p ~/.kube
          echo "${{ secrets.KUBE_CONFIG }}" | base64 -d > ~/.kube/config
          chmod 600 ~/.kube/config

      - name: 롤링 업데이트
        run: |
          kubectl set image deployment/web \
            web=ghcr.io/${{ github.repository }}:sha-${GITHUB_SHA::7} \
            -n production
          kubectl rollout status deployment/web -n production --timeout=180s

      - name: 실패 시 롤백
        if: failure()
        run: kubectl rollout undo deployment/web -n production

④ 서버리스 / 매니지드 플랫폼

Vercel, Netlify, Cloud Run, Lambda 등은 대부분 공식 Action이나 CLI가 있어서
npx vercel deploy --prod, gcloud run deploy, serverless deploy 한 줄로 끝나.
이 경우 핵심은 인증을 OIDC로 처리했는가야.

🧬 10장. 재사용 워크플로 & Composite Action

서비스가 10개면 워크플로도 10개. 그런데 내용은 거의 복붙이지.
이때 복붙을 모듈화하는 두 가지 방법이 있어.

Reusable Workflow (Job 단위 재사용)

# .github/workflows/reusable-node-ci.yml
name: Reusable Node CI
on:
  workflow_call:
    inputs:
      node-version:
        type: string
        default: '20'
      working-directory:
        type: string
        default: '.'
    secrets:
      NPM_TOKEN:
        required: false

jobs:
  ci:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: ${{ inputs.working-directory }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: npm
      - run: npm ci
      - run: npm test

# 호출하는 쪽
jobs:
  web:
    uses: ./.github/workflows/reusable-node-ci.yml
    with:
      node-version: '20'
      working-directory: apps/web
    secrets: inherit

Composite Action (Step 단위 재사용)

# .github/actions/setup-project/action.yml
name: 'Setup Project'
description: '노드 세팅 + 의존성 설치'
inputs:
  node-version:
    default: '20'
runs:
  using: 'composite'
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: ${{ inputs.node-version }}
        cache: npm
    - run: npm ci
      shell: bash      # composite에서는 shell 필수!

🎛️ 11장. 조건부 실행, 표현식, 출력값

if 표현식

      - name: main일 때만
        if: github.ref == 'refs/heads/main'
        run: echo "운영 브랜치"

      - name: PR에 특정 라벨 있을 때만
        if: contains(github.event.pull_request.labels.*.name, 'deploy-preview')
        run: ./preview.sh

      - name: 이전 스텝 실패해도 실행
        if: always()
        run: ./cleanup.sh

      - name: 실패했을 때만 알림
        if: failure()
        run: ./notify-slack.sh

      - name: 커밋 메시지에 skip 없을 때
        if: "!contains(github.event.head_commit.message, '[skip deploy]')"
        run: ./deploy.sh

Step/Job 출력값 주고받기

jobs:
  prepare:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.ver.outputs.value }}
    steps:
      - uses: actions/checkout@v4
      - id: ver
        run: echo "value=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT

  release:
    needs: prepare
    runs-on: ubuntu-latest
    steps:
      - run: echo "배포 버전 ${{ needs.prepare.outputs.version }}"

        env:
          TITLE: ${{ github.event.issue.title }}
        run: echo "$TITLE"

알아두면 편한 컨텍스트

🖥️ 12장. Self-hosted Runner — 언제 필요한가

GitHub 러너는 매번 깨끗한 새 VM이라 안전하지만, 이런 상황엔 한계가 있어.

💸 13장. 비용과 속도 최적화 체크리스트

프라이빗 레포는 분(minutes) 단위 과금이고, OS별 배수가 있어.

최적화 12계명

🧯 14장. 디버깅 생존 가이드

자주 나는 에러와 해결

디버그 무기 3종

      - run: |
          echo "=== env ==="; env | sort
          echo "=== pwd ==="; pwd; ls -al
          echo "=== versions ==="; node -v; npm -v

      - run: |
          echo "### ✅ 배포 완료" >> $GITHUB_STEP_SUMMARY
          echo "- 버전: \`${GITHUB_SHA::7}\`" >> $GITHUB_STEP_SUMMARY

🌱 15장. 성숙한 파이프라인으로 가는 로드맵

단계별 실행 과제

🧾 16장. 실무 통합 예시 — 하나로 합쳐보기

name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  # 1) 품질 검증 (모든 PR)
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-retries 5
        ports: [ '5432:5432' ]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20, cache: npm }
      - run: npm ci
      - run: npm run lint
      - run: npm test
        env:
          DATABASE_URL: postgres://postgres:test@localhost:5432/postgres
      - name: 요약 기록
        if: always()
        run: echo "### 테스트 결과: ${{ job.status }}" >> $GITHUB_STEP_SUMMARY

  # 2) 이미지 빌드 (main만)
  build:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    outputs:
      tag: ${{ steps.t.outputs.tag }}
    steps:
      - uses: actions/checkout@v4
      - id: t
        run: echo "tag=sha-${GITHUB_SHA::7}" >> $GITHUB_OUTPUT
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ steps.t.outputs.tag }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

  # 3) staging 자동 배포
  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - run: echo "staging 배포 ${{ needs.build.outputs.tag }}"

  # 4) production 승인 후 배포
  deploy-prod:
    needs: [ build, deploy-staging ]
    runs-on: ubuntu-latest
    environment:
      name: production
      url: https://example.com
    steps:
      - run: echo "production 배포 ${{ needs.build.outputs.tag }}"
      - name: 실패 알림
        if: failure()
        run: echo "롤백 절차 시작"

🔒 17장. 보안 하드닝 최종 점검

🎓 에필로그: 자동화는 결국 '팀의 태도'

여기까지 왔으면 이제 알 거야.
GitHub Actions는 YAML 문법 싸움이 아니라 팀의 약속을 코드로 굳히는 작업이라는 걸.

"테스트는 통과해야 머지한다"
"운영 배포는 두 명이 승인한다"
"롤백은 3분 안에 가능해야 한다"

이런 규칙을 사람 기억에 맡기면 무너지고, 파이프라인에 새기면 유지된다.
그게 DevOps의 본질이야. 도구가 문화를 지켜주는 구조를 만드는 거.

클라우드/DevOps 영역은 혼자 파면 삽질 시간이 유독 길어.
이미 겪어본 사람의 30분 상담이 혼자 3일 헤매는 걸 대체하는 분야거든.
그래서 재능넷 같은 재능 공유 플랫폼에서 인프라·CI/CD 실무자에게 파이프라인 리뷰를 받아보는 건
꽤 현실적인 선택이야. 남의 워크플로 하나 읽는 것만으로도 배우는 게 많으니까.

그리고 지금 읽고 있는 재능넷 '지식인의 숲'처럼
정리된 지식을 먼저 훑고 손을 대면, 삽질의 절대량이 확실히 줄어든다.

자, 이제 터미널 열고 mkdir -p .github/workflows 부터 가보자. 🚀
첫 초록 체크의 그 쾌감, 직접 느껴봐야 해.