GitHub Actions 사용법 총정리 — 워크플로 작성부터 자동 배포까지

코드를 깃허브에 푸시할 때마다 자동으로 테스트가 돌아가고, 문제없으면 서버에 배포까지 되면 얼마나 편할까요? GitHub Actions가 바로 이걸 가능하게 해줍니다.

이 글에서는 GitHub Actions의 개념부터 실제 워크플로 작성법, 마켓플레이스 활용, 시크릿 관리까지 한 번에 정리합니다. 처음 접하는 분도 이 글 하나면 CI/CD 파이프라인을 직접 만들 수 있습니다.

GitHub Actions란?

GitHub Actions는 깃허브에서 제공하는 CI/CD 자동화 플랫폼입니다. 코드 저장소(Repository)에서 특정 이벤트가 발생하면 미리 정의해둔 작업을 자동으로 실행해줍니다.

예를 들어 이런 것들이 가능합니다:

• 코드 푸시할 때마다 자동으로 테스트 실행
• PR(Pull Request) 올라올 때 코드 품질 검사
• 릴리스 태그 생성 시 자동 배포
• 매일 정해진 시간에 스크립트 실행

GitHub Actions 공식 페이지. "Automate your workflow from idea to production"이라는 슬로건처럼 개발 전 과정을 자동화할 수 있습니다.

왜 GitHub Actions를 써야 할까?

Jenkins, CircleCI, Travis CI 같은 CI/CD 도구들이 있는데 왜 굳이 GitHub Actions일까요?

1. 깃허브와 완벽 통합: 별도 서비스 연동 없이 저장소 안에서 바로 설정. 코드와 워크플로가 한 곳에 있어서 관리가 쉽습니다.

2. 무료 사용량 넉넉: Public 저장소는 완전 무료, Private 저장소도 월 2,000분(약 33시간) 무료입니다.

3. 마켓플레이스: 남들이 만들어둔 재사용 가능한 액션이 수천 개. 직접 코드 짤 필요 없이 가져다 쓰면 됩니다.

4. 매트릭스 빌드: 여러 OS, 여러 언어 버전에서 동시 테스트 가능. "Node 18, 20, 22에서 전부 돌려봐" 같은 게 YAML 몇 줄이면 됩니다.

핵심 구조 이해하기

GitHub Actions를 사용하려면 5가지 핵심 개념을 알아야 합니다.

이벤트 (Event)

워크플로를 실행시키는 트리거입니다. push, pull_request, schedule(크론), workflow_dispatch(수동 실행) 등이 있습니다.

워크플로 (Workflow)

자동화 프로세스 전체를 말합니다. .github/workflows/ 폴더에 YAML 파일로 정의합니다. 하나의 저장소에 여러 워크플로를 만들 수 있습니다.

잡 (Job)

워크플로 안의 작업 단위입니다. 기본적으로 병렬 실행되고, needs 키워드로 순서를 지정할 수 있습니다.

스텝 (Step)

잡 안의 개별 동작입니다. 셸 명령어(run)를 직접 실행하거나, 재사용 가능한 액션(uses)을 불러올 수 있습니다.

러너 (Runner)

워크플로를 실행하는 서버입니다. GitHub에서 제공하는 Ubuntu, Windows, macOS 러너를 쓰거나, 자체 서버를 러너로 등록할 수 있습니다.

GitHub Actions 공식 문서에서 각 구성 요소에 대한 자세한 설명을 확인할 수 있습니다.

첫 번째 워크플로 만들기 (실전)

이제 직접 워크플로를 만들어보겠습니다. 가장 많이 쓰는 패턴인 "푸시하면 테스트 돌리기"를 구현합니다.

1단계: 워크플로 파일 생성

저장소 루트에 .github/workflows/ci.yml 파일을 만듭니다.

위 예시를 하나씩 뜯어보겠습니다:

• name: 워크플로 이름. Actions 탭에 표시됩니다
• on: 트리거 조건. push와 PR 이벤트에 반응하도록 설정
• jobs: 실행할 작업 정의
• runs-on: 어떤 환경에서 실행할지 (ubuntu-latest가 가장 일반적)
• steps: 순서대로 실행할 동작들
• uses: 마켓플레이스의 액션을 가져다 쓸 때
• run: 직접 셸 명령어를 실행할 때

2단계: 커밋하고 확인하기

파일을 커밋하고 푸시하면 자동으로 워크플로가 실행됩니다. 저장소의 Actions 탭에서 실행 상태를 확인할 수 있습니다.

자주 쓰는 워크플로 패턴

Node.js 프로젝트 CI

Node.js 프로젝트에서 가장 기본적인 CI 워크플로입니다. GitHub에서 공식 제공하는 스타터 워크플로를 기반으로 합니다.

name: Node.js CI
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18.x, 20.x, 22.x]
    steps:
      - uses: actions/checkout@v4
      - name: Use Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm ci
      - run: npm run build --if-present
      - run: npm test

strategy.matrix를 사용하면 Node 18, 20, 22 버전에서 동시에 테스트를 돌릴 수 있습니다.

자동 배포 워크플로

name: Deploy
on:
  push:
    branches: [ main ]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: Deploy to Server
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /var/www/myapp
            git pull origin main
            npm ci --production
            pm2 restart all

main 브랜치에 푸시되면 자동으로 서버에 배포합니다. 민감한 정보는 secrets로 관리합니다.

마켓플레이스 활용하기

GitHub Actions Marketplace에는 2만 개 이상의 재사용 가능한 액션이 있습니다. 직접 만들 필요 없이 가져다 쓰면 됩니다.

가장 많이 쓰는 액션 TOP 5

액션	용도	사용법
actions/checkout	코드 체크아웃	거의 모든 워크플로에 필수
actions/setup-node	Node.js 환경 설정	캐시 옵션으로 속도 향상
actions/cache	의존성 캐싱	빌드 시간 대폭 단축
actions/upload-artifact	빌드 결과물 저장	잡 간 데이터 전달
peaceiris/actions-gh-pages	GitHub Pages 배포	정적 사이트 자동 배포

가장 기본이 되는 actions/checkout 액션. 거의 모든 워크플로의 첫 번째 스텝에 들어갑니다.

시크릿(Secrets) 관리

API 키, 비밀번호, 토큰 같은 민감한 정보를 워크플로에서 안전하게 사용하는 방법입니다.

시크릿 등록 방법

1. 저장소 → Settings → Secrets and variables → Actions
2. New repository secret 클릭
3. 이름과 값 입력 후 저장

워크플로에서 사용

steps:
  - name: Deploy
    env:
      API_KEY: ${{ secrets.MY_API_KEY }}
    run: echo "Deploying with secret..."

시크릿은 로그에도 마스킹 처리되어 노출되지 않습니다. 환경변수로 주입하거나 with로 액션에 전달할 수 있습니다.

워크플로 문법 핵심 정리

트리거 설정 (on)

# 특정 브랜치만
on:
  push:
    branches: [main, develop]

# 크론 스케줄 (매일 새벽 3시)
on:
  schedule:
    - cron: '0 18 * * *'  # UTC 기준

# 수동 실행
on:
  workflow_dispatch:
    inputs:
      environment:
        description: '배포 환경'
        required: true
        default: 'staging'

조건부 실행 (if)

jobs:
  deploy:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - run: echo "main 브랜치에서만 실행"

환경 변수와 컨텍스트

env:
  NODE_ENV: production

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: echo "${{ github.repository }}"
      - run: echo "${{ github.actor }}"
      - run: echo "${{ env.NODE_ENV }}"

스타터 워크플로 활용

GitHub에서는 다양한 언어와 프레임워크에 맞는 스타터 워크플로 템플릿을 제공합니다. 저장소의 Actions 탭에서 바로 추가할 수 있습니다.

Python, Java, Go, Ruby, .NET 등 주요 언어의 CI 템플릿이 준비되어 있어서, YAML을 처음부터 작성할 필요 없이 템플릿을 기반으로 커스터마이징하면 됩니다.

실무 팁

1. 캐시 활용으로 빌드 시간 단축

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

캐시를 사용하면 npm install 시간을 70~80% 줄일 수 있습니다.

2. 실패 시 알림 받기

- name: Slack 알림
  if: failure()
  uses: 8398a7/action-slack@v3
  with:
    status: ${{ job.status }}
    fields: repo,commit,author
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

3. timeout 설정하기

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 15  # 15분 초과 시 자동 취소

무료 사용량과 요금

GitHub Actions의 요금 구조는 꽤 관대합니다:

• Public 저장소: 완전 무료 (무제한)
• Free 플랜: 월 2,000분 (약 33시간)
• Pro 플랜: 월 3,000분
• Team 플랜: 월 3,000분
• Enterprise: 월 50,000분

참고로 Linux 러너 기준이고, Windows는 2배, macOS는 10배로 분 계산됩니다.

마무리

GitHub Actions는 별도 서버 없이도 CI/CD를 구축할 수 있게 해주는 강력한 도구입니다. 핵심 정리:

1. .github/workflows/에 YAML 파일 작성
2. on으로 트리거 설정, jobs와 steps로 작업 정의
3. 마켓플레이스의 액션 활용으로 개발 시간 단축
4. 시크릿으로 민감 정보 안전하게 관리
5. 캐시와 매트릭스 빌드로 효율 극대화

공식 문서(GitHub Actions Docs)에서 더 다양한 예제를 확인할 수 있습니다. 한 번 설정해두면 개발 생산성이 확실히 달라지니, 오늘 바로 첫 워크플로를 만들어보세요.

---

✨ 자동화가 필요하신가요?

SNS/유튜브 자동 포스팅, AI 자동화 구축 — 맞춤 상담 가능합니다.

👉 크몽에서 의뢰하기

📱 인스타: @dev_orijin

이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.